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

dstf/backends/julia/run_persistent.jl

@@ -0,0 +1,167 @@
+# Framework-generated Julia driver for the PERSISTENT worker path (D78).
+#
+# A long-lived Julia process reads JSON-per-line test requests from stdin
+# and writes JSON-per-line responses to stdout. Package load (MTK, ODE,
+# JSON3) happens ONCE at startup; per-test cost becomes just
+# ``include(user_file)`` + ``structural_simplify`` + ``solve``.
+#
+# Request:
+#   {"user_file": "...", "stop_time": 10.0, "tolerance": 1e-6,
+#    "result_path": "...", "test_key": "..."}
+# Response:
+#   {"test_key": "...", "status": "ok"|"fail", "elapsed": 12.3, "error": "..."}
+#
+# Control messages:
+#   {"cmd": "quit"}  → exits cleanly.
+#   {"cmd": "ready"} → emits a ready pulse (used for startup handshake).
+#
+# Re-inclusion: ``include`` re-evaluates the user file at module scope,
+# redefining ``build_mtk_system``. ``Base.invokelatest`` forces the
+# generation boundary so the freshly-redefined function is called rather
+# than an older compiled version the worker might still have bound.
+
+using Printf
+using JSON3
+using ModelingToolkit
+using OrdinaryDiffEq
+
+# Signal readiness to the dispatcher. The parent can use this as a hand-
+# shake marker indicating `using` has completed and the worker is ready
+# to accept test requests.
+println(stdout, JSON3.write(Dict("event" => "ready", "pid" => getpid())))
+flush(stdout)
+
+function handle_request(req)
+    user_file = req["user_file"]
+    stop_time = Float64(req["stop_time"])
+    tol = Float64(req["tolerance"])
+    result_path = req["result_path"]
+    test_key = get(req, "test_key", "")
+
+    t_start = time()
+    try
+        # review 2026-07-06 (finding 27): in this long-lived process a user
+        # file that fails to (re)define build_mtk_system would silently reuse
+        # the PREVIOUS test's definition. Poison the binding with a sentinel
+        # method BEFORE every include — if the file doesn't replace it, the
+        # invokelatest below raises this error instead of simulating the
+        # wrong model (covers bad-file-after-good-file, not just the first).
+        Main.eval(:(build_mtk_system() = error(
+            "user file did not define build_mtk_system() — stale-definition guard"
+        )))
+        include(user_file)
+        nt = Base.invokelatest(build_mtk_system)
+        prob = ModelingToolkit.ODEProblem(nt.sys, nt.u0, (0.0, stop_time), nt.ps)
+        sol = OrdinaryDiffEq.solve(prob, OrdinaryDiffEq.Tsit5(); reltol=tol)
+
+        # review 2026-07-06 (finding 4): mirror run_test.jl — a diverged /
+        # truncated solve must not be reported (or baselined) as success.
+        if !OrdinaryDiffEq.SciMLBase.successful_retcode(sol)
+            error("solver did not succeed: retcode=" * string(sol.retcode))
+        end
+        if isempty(sol.t) || abs(sol.t[end] - stop_time) > 1e-6 * max(abs(stop_time), 1.0)
+            t_end = isempty(sol.t) ? "none" : string(sol.t[end])
+            error("solve stopped at t=" * t_end * " before stop_time=" *
+                  string(stop_time) * " (retcode=" * string(sol.retcode) * ")")
+        end
+
+        # Collect unknowns AND observables — see run_test.jl for rationale.
+        unk = ModelingToolkit.unknowns(nt.sys)
+        obs_eqs = ModelingToolkit.observed(nt.sys)
+        variables = Dict{String, Vector{Float64}}()
+        for u in unk
+            name = string(u)
+            stripped = endswith(name, "(t)") ? name[1:end-3] : name
+            variables[stripped] = Float64.(sol[u])
+        end
+        for eq in obs_eqs
+            lhs = eq.lhs
+            name = string(lhs)
+            stripped = endswith(name, "(t)") ? name[1:end-3] : name
+            if haskey(variables, stripped) || startswith(stripped, "ˍ")
+                continue
+            end
+            try
+                variables[stripped] = Float64.(sol[lhs])
+            catch
+            end
+        end
+
+        payload = Dict(
+            "success" => true,
+            "time" => Float64.(sol.t),
+            "variables" => variables,
+        )
+        open(result_path, "w") do io
+            JSON3.write(io, payload)
+        end
+
+        elapsed = time() - t_start
+        println(stdout, JSON3.write(Dict(
+            "test_key" => test_key,
+            "status" => "ok",
+            "elapsed" => elapsed,
+            "n_vars" => length(variables),
+            "n_time" => length(sol.t),
+        )))
+        flush(stdout)
+    catch e
+        elapsed = time() - t_start
+        buf = IOBuffer()
+        showerror(buf, e, catch_backtrace())
+        msg = String(take!(buf))
+        # Best-effort failure payload so the backend's read_result path still
+        # gets a structured response.
+        try
+            open(result_path, "w") do io
+                JSON3.write(io, Dict(
+                    "success" => false,
+                    "error" => msg,
+                    "time" => Float64[],
+                    "variables" => Dict{String, Vector{Float64}}(),
+                ))
+            end
+        catch
+        end
+        println(stdout, JSON3.write(Dict(
+            "test_key" => test_key,
+            "status" => "fail",
+            "elapsed" => elapsed,
+            "error" => msg,
+        )))
+        flush(stdout)
+    end
+end
+
+# Main loop.
+while !eof(stdin)
+    line = try
+        readline(stdin)
+    catch e
+        break
+    end
+    isempty(line) && continue
+    req = try
+        JSON3.read(line)
+    catch e
+        println(stderr, "Failed to parse request line: ", line)
+        continue
+    end
+    # Control messages first.
+    cmd = get(req, "cmd", "")
+    if cmd == "quit"
+        println(stdout, JSON3.write(Dict("event" => "quitting")))
+        flush(stdout)
+        break
+    elseif cmd == "ready"
+        println(stdout, JSON3.write(Dict("event" => "ready", "pid" => getpid())))
+        flush(stdout)
+        continue
+    end
+    # Test request.
+    if !haskey(req, "user_file")
+        println(stderr, "Ignoring request with no user_file: ", line)
+        continue
+    end
+    handle_request(req)
+end

dstf/backends/julia/run_test.jl

@@ -0,0 +1,146 @@
+# Framework-generated Julia driver for a single test.
+#
+# Invoked by JuliaBackend as:
+#   julia --project=<examples_project> run_test.jl <user_file> <stop_time> <tol> <result_path>
+#
+# The user file must export `build_mtk_system()` returning a NamedTuple with:
+#   sys :: ODESystem   — structurally simplified
+#   u0  :: Vector      — initial conditions (pairs of Symbol => value)
+#   ps  :: Vector      — parameter values    (pairs of Symbol => value)
+#
+# Result file is JSON:
+#   { "success": bool,
+#     "time": [...],
+#     "variables": {"name": [...], ...},
+#     "error": "..." (only if success == false) }
+#
+# The wrapper intentionally catches exceptions so the framework always
+# gets a structured result (success=false + error) rather than a
+# process-level crash.
+
+using Printf
+
+const USER_FILE   = ARGS[1]
+const STOP_TIME   = parse(Float64, ARGS[2])
+const TOLERANCE   = parse(Float64, ARGS[3])
+const RESULT_PATH = ARGS[4]
+
+# review 2026-07-06 (finding 75): the failure JSON is hand-built (JSON3 may
+# not have loaded when the failure happens). Julia's repr()-style escaping
+# is NOT JSON (`\$` is invalid) — real error detail was lost to parse
+# errors. Minimal manual JSON string escaper instead.
+function json_escape(s::AbstractString)
+    buf = IOBuffer()
+    for c in s
+        if c == '\\'
+            write(buf, "\\\\")
+        elseif c == '"'
+            write(buf, "\\\"")
+        elseif c == '\n'
+            write(buf, "\\n")
+        elseif c == '\r'
+            write(buf, "\\r")
+        elseif c == '\t'
+            write(buf, "\\t")
+        elseif c < ' '
+            write(buf, "\\u" * string(UInt32(c), base=16, pad=4))
+        else
+            write(buf, c)
+        end
+    end
+    return String(take!(buf))
+end
+
+function write_failure(msg)
+    open(RESULT_PATH, "w") do io
+        write(io, string("{\"success\": false, \"error\": \"",
+                         json_escape(string(msg)),
+                         "\", \"time\": [], \"variables\": {}}"))
+    end
+end
+
+try
+    import ModelingToolkit
+    import OrdinaryDiffEq
+    import JSON3
+
+    # Load the user file. It should export `build_mtk_system()`.
+    include(USER_FILE)
+    isdefined(@__MODULE__, :build_mtk_system) || error(
+        "user file $(USER_FILE) must export build_mtk_system()")
+
+    nt = build_mtk_system()
+    haskey(nt, :sys) || error("build_mtk_system() must return NamedTuple with :sys")
+
+    u0 = haskey(nt, :u0) ? nt.u0 : []
+    ps = haskey(nt, :ps) ? nt.ps : []
+
+    prob = ModelingToolkit.ODEProblem(nt.sys, u0, (0.0, STOP_TIME), ps)
+    sol = OrdinaryDiffEq.solve(prob, OrdinaryDiffEq.Tsit5(); reltol=TOLERANCE)
+
+    # review 2026-07-06 (finding 4): a diverged / unstable / maxiters-
+    # truncated solve must not be written as success — with --accept the
+    # truncated trajectory would become the regression baseline. Check the
+    # retcode AND that integration actually reached stop_time.
+    if !OrdinaryDiffEq.SciMLBase.successful_retcode(sol)
+        error("solver did not succeed: retcode=" * string(sol.retcode))
+    end
+    if isempty(sol.t) || abs(sol.t[end] - STOP_TIME) > 1e-6 * max(abs(STOP_TIME), 1.0)
+        t_end = isempty(sol.t) ? "none" : string(sol.t[end])
+        error("solve stopped at t=" * t_end * " before stop_time=" *
+              string(STOP_TIME) * " (retcode=" * string(sol.retcode) * ")")
+    end
+
+    # Collect unknowns (state variables) AND observables (algebraic
+    # expressions like `y ~ a*x1 + b*x2` that structural_simplify
+    # promotes out of the unknowns list but are still materializable
+    # from the solution via sol[expr]). Users authoring MTK tests
+    # typically expect both to be accessible.
+    unk = ModelingToolkit.unknowns(nt.sys)
+    obs_eqs = ModelingToolkit.observed(nt.sys)
+    variables = Dict{String, Vector{Float64}}()
+    for u in unk
+        name = string(u)
+        stripped = endswith(name, "(t)") ? name[1:end-3] : name
+        variables[stripped] = Float64.(sol[u])
+    end
+    for eq in obs_eqs
+        lhs = eq.lhs
+        name = string(lhs)
+        stripped = endswith(name, "(t)") ? name[1:end-3] : name
+        # Skip if already captured as an unknown (shouldn't happen but
+        # defensive) or if the name is a helper symbol MTK introduced.
+        if haskey(variables, stripped) || startswith(stripped, "ˍ")
+            continue
+        end
+        try
+            variables[stripped] = Float64.(sol[lhs])
+        catch
+            # Some observables can't be evaluated (e.g., dependent on
+            # parameters only); skip silently rather than fail the test.
+        end
+    end
+
+    payload = Dict(
+        "success" => true,
+        "time" => Float64.(sol.t),
+        "variables" => variables,
+    )
+    open(RESULT_PATH, "w") do io
+        JSON3.write(io, payload)
+    end
+
+    @printf "OK: %d variables, %d time points\n" length(variables) length(sol.t)
+catch e
+    buf = IOBuffer()
+    showerror(buf, e, catch_backtrace())
+    msg = String(take!(buf))
+    @printf stderr "FAIL: %s\n" msg
+    try
+        write_failure(msg)
+    catch
+        # If even writing the failure JSON fails, at least exit nonzero.
+        exit(2)
+    end
+    exit(1)
+end

dstf/backends/openmodelica/__init__.py

@@ -0,0 +1,21 @@
+"""OpenModelica backend.
+
+Two modes:
+
+- Persistent-worker (default CLI path): long-lived OMCSessionZMQ per worker
+  via OMPython (:mod:`.persistent_backend`). Cuts wall-time for repeated-test
+  runs since MSL and library loads are amortized across the whole batch.
+- Batch fallback (``--batch``): one ``omc`` subprocess per test driven by a
+  generated ``simulate.mos`` (:mod:`.backend`). Used automatically when
+  OMPython is unavailable.
+
+FMU export (``buildModelFMU``) is still a deferred follow-up.
+
+One-time bootstrap (per machine) to install the Modelica Standard Library:
+
+    omc -e 'updatePackageIndex(); installPackage(Modelica); getErrorString();'
+"""
+
+from .backend import OpenModelicaBackend, OpenModelicaConfig
+
+__all__ = ["OpenModelicaConfig", "OpenModelicaBackend"]

dstf/backends/openmodelica/backend.py

@@ -0,0 +1,368 @@
+"""OpenModelica backend: omc subprocess + .mos scripts (batch fallback).
+
+Per-test omc subprocess driven by a generated ``simulate.mos``. The
+persistent-worker counterpart lives in :mod:`.persistent_backend` and is the
+default CLI path; this one is reached with the ``--batch`` CLI flag. There is
+no automatic fallback — a missing OMPython aborts the run (see
+``backends.select_backend``). FMU export (``buildModelFMU``) is still a follow-up.
+
+One-time per machine (bootstrap MSL):
+
+    omc -e 'updatePackageIndex(); installPackage(Modelica); getErrorString();'
+
+``backend_setup`` commands run between library-loading and ``cd()``. These
+are emitted as-is and are backend-specific (Dymola-syntactic commands like
+``Advanced.UI.TranslationInCommandLog := true`` will fail on omc). Users
+maintain a separate ``testing.linux.json`` for the OpenModelica run.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from ...config import Config
+from ...discovery.test_registry import TestModel
+from .. import register
+from ..base import Backend
+from ..common import result_files
+from ..common.mat_reader import mat_reaches_time, read_result_mat
+from ..common.proc_output import decode_output
+from ..common.result_variables import (
+    compute_needed_variables,
+    extract_variables,
+    fold_diagnostics_into_statistics,
+    unfinished_result,
+)
+from ..types import (
+    Capability,
+    DatasetType,
+    TestResult,
+    TestRunResult,
+    timeout_message,
+)
+from .init_xml import with_system_size
+from .log_parser import parse_omc_stdout
+from .mos_generator import build_simulate_mos
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class OpenModelicaConfig:
+    """OpenModelica-specific settings extracted from the universal Config."""
+
+    omc_path: str
+    backend_setup: tuple[str, ...] = ()
+    diagnostic_variables: tuple[str, ...] = ("CPUtime", "EventCounter")
+    std_version: str = "latest"
+    #: Write each output row to the result file as it is produced
+    #: (``Config.live_results``).
+    mat_sync: bool = False
+
+    @classmethod
+    def from_config(cls, config: Config) -> OpenModelicaConfig:
+        # Config.__post_init__ now resolves backend_path via
+        # BACKEND_BINARY_NAMES, so the Config-supplied value is authoritative.
+        # Fall through to `omc` on PATH only if the config didn't set one at
+        # all (e.g., stubbed tests that bypass __post_init__).
+        omc_path = config.backend_path or shutil.which("omc") or "omc"
+        return cls(
+            omc_path=omc_path,
+            backend_setup=tuple(config.backend_setup),
+            diagnostic_variables=tuple(config.diagnostic_variables),
+            mat_sync=config.live_results,
+        )
+
+
+@register("OpenModelica")
+class OpenModelicaBackend(Backend):
+    """OpenModelica backend using omc as a subprocess driver."""
+
+    capabilities = frozenset(
+        {
+            Capability.BATCH_FALLBACK,
+            Capability.PERSISTENT_WORKERS,
+            # The simulation executable appends result_res.mat as it goes:
+            # in blocks, or a row at a time under `-mat_sync=1`.
+            Capability.LIVE_RESULTS,
+        }
+    )
+    produced_datasets = frozenset({DatasetType.TIME_SERIES})
+    artifact_files = (
+        ("simulate.mos", "Simulation script"),
+        ("result_res.mat", "Result file"),
+        ("result.log", "Simulation log"),
+        ("result_info.json", "Model info"),
+        ("omc_stdout.txt", "omc output"),
+    )
+
+    RESULT_MAT_FILENAME = "result_res.mat"
+    INIT_XML_FILENAME = "result_init.xml"
+    STDOUT_FILENAME = "omc_stdout.txt"
+    MOS_FILENAME = "simulate.mos"
+
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.om_config = OpenModelicaConfig.from_config(config)
+
+    @classmethod
+    def persistent_backend_cls(cls):
+        from .persistent_backend import PersistentOpenModelicaBackend
+
+        return PersistentOpenModelicaBackend
+
+    # ------------------------------------------------------------------
+    # Simulation
+    # ------------------------------------------------------------------
+
+    def run_single_test(
+        self,
+        test: TestModel,
+        test_key: str,
+        index: int,
+        total: int,
+    ) -> TestRunResult:
+        test_dir = self.config.work_dir / test_key
+        test_dir.mkdir(parents=True, exist_ok=True)
+
+        if self.progress:
+            self.progress.on_start(test_key)
+            self.progress.on_phase(test_key, "translating")
+
+        # MSL is always required for Modelica simulation. Dymola auto-loads
+        # it; OM needs an explicit loadModel(Modelica). Auto-inject if the
+        # user didn't already list it, so a single testing.json with an
+        # empty ``dependencies`` works across both backends.
+        deps = list(self.config.dependencies)
+        if "Modelica" not in deps and not any(
+            str(d).rstrip("/\\").endswith("Modelica") for d in deps
+        ):
+            deps = ["Modelica"] + deps
+
+        # Build and write the .mos
+        mos_text = build_simulate_mos(
+            test=test,
+            test_dir=test_dir,
+            library_package_mo=self.config.library_dir / "package.mo",
+            dependencies=deps,
+            backend_setup=list(self.om_config.backend_setup),
+            diagnostic_vars=list(self.om_config.diagnostic_variables),
+            std_version=self.om_config.std_version,
+            mat_sync=self.om_config.mat_sync,
+        )
+        mos_path = test_dir / self.MOS_FILENAME
+        mos_path.write_text(mos_text, encoding="utf-8")
+
+        timeout = float(
+            test.timeout if test.timeout is not None else self.config.timeout,
+        )
+
+        wall_start = time.monotonic()
+        try:
+            proc = subprocess.run(
+                [self.om_config.omc_path, self.MOS_FILENAME],
+                cwd=test_dir,
+                capture_output=True,
+                text=True,
+                # review 2026-07-06 (finding 75): pin utf-8 + replace so a
+                # non-ASCII omc message can't crash the reader on cp1252 hosts.
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            elapsed = time.monotonic() - wall_start
+            # review 2026-07-06 (finding 23): TimeoutExpired.stdout is bytes
+            # even with text=True — decode_output handles None/bytes/str.
+            (test_dir / self.STDOUT_FILENAME).write_text(
+                decode_output(exc.stdout) + "\n[TimeoutExpired]\n",
+                encoding="utf-8",
+            )
+            msg = timeout_message(f"omc exceeded {timeout}s timeout")
+            logger.warning("Test %s: %s", test.model_id, msg)
+            if self.progress:
+                self.progress.on_finish(
+                    test_key,
+                    success=False,
+                    elapsed=elapsed,
+                    detail=msg,
+                    timed_out=True,
+                )
+            return TestRunResult(
+                model_id=test.model_id,
+                test_key=test_key,
+                success=False,
+                elapsed=elapsed,
+                error_message=msg,
+                timed_out=True,
+            )
+
+        elapsed = time.monotonic() - wall_start
+        stdout_text = proc.stdout or ""
+        (test_dir / self.STDOUT_FILENAME).write_text(stdout_text, encoding="utf-8")
+
+        parsed = parse_omc_stdout(stdout_text)
+
+        # Build statistics.timing — wall-clock seconds captured Python-side.
+        stats: dict = {}
+        if parsed.timings is not None:
+            stats["timing"] = dict(parsed.timings)
+
+        # Translation-wall = sum of all pre-simulation phases.
+        translation_wall: float | None = None
+        sim_wall: float | None = None
+        if parsed.timings is not None:
+            t = parsed.timings
+            translation_wall = (
+                t.get("frontend", 0.0)
+                + t.get("backend", 0.0)
+                + t.get("simcode", 0.0)
+                + t.get("templates", 0.0)
+                + t.get("compile", 0.0)
+            )
+            sim_wall = t.get("simulation")
+
+        mat_path = test_dir / self.RESULT_MAT_FILENAME
+        if parsed.success and mat_path.exists():
+            # Belt on the accept-integrity invariant (D93 precedent): a
+            # partial .mat blessed by --accept poisons the baseline, so
+            # even a success-reporting record must show a trajectory that
+            # reached stop_time. Empirically (D99, omc 1.27) mid-run
+            # aborts return an EMPTY resultFile and never take this
+            # branch — this guards against a future omc populating
+            # resultFile on partial runs or a truncated write.
+            reached, last_time = mat_reaches_time(mat_path, float(test.stop_time))
+            if reached:
+                if self.progress:
+                    self.progress.on_phase(test_key, "simulating")
+                    self.progress.on_finish(test_key, success=True, elapsed=elapsed)
+                return TestRunResult(
+                    model_id=test.model_id,
+                    test_key=test_key,
+                    success=True,
+                    elapsed=elapsed,
+                    translation_wall=translation_wall,
+                    sim_wall=sim_wall,
+                    statistics=stats or None,
+                )
+            parsed.error_notices.append(
+                f"simulate() reported success but {self.RESULT_MAT_FILENAME} "
+                f"reaches t={last_time!r} of stop_time={test.stop_time} — "
+                f"partial result refused"
+            )
+
+        # Failure: build an error message that surfaces both pre-record
+        # notices and the simulate() record's `messages` field.
+        err_parts: list[str] = []
+        if proc.returncode != 0:
+            err_parts.append(f"omc exit code {proc.returncode}")
+        if parsed.error_notices:
+            err_parts.append("; ".join(parsed.error_notices[:5]))
+        if parsed.messages:
+            err_parts.append(parsed.messages.strip())
+        if not parsed.result_file:
+            err_parts.append("no result file produced")
+        msg = " | ".join(p for p in err_parts if p)[:2048] or "omc simulation failed"
+
+        # If MSL wasn't installed, surface a clear hint.
+        if any("Failed to load package Modelica" in n for n in parsed.error_notices):
+            msg = (
+                "MSL not installed. Run: omc -e "
+                "'updatePackageIndex(); installPackage(Modelica); "
+                "getErrorString();' | " + msg
+            )
+
+        if self.progress:
+            self.progress.on_finish(
+                test_key,
+                success=False,
+                elapsed=elapsed,
+                detail=msg[:120],
+            )
+        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,
+            statistics=stats or None,
+        )
+
+    # ------------------------------------------------------------------
+    # Reading
+    # ------------------------------------------------------------------
+
+    def read_result(
+        self,
+        test: TestModel,
+        test_key: str,
+        run_result: TestRunResult | None,
+    ) -> TestResult:
+        stats = (
+            dict(run_result.statistics)
+            if run_result and run_result.statistics
+            else None
+        )
+        test_dir = self.config.work_dir / test_key
+        mat_path = test_dir / self.RESULT_MAT_FILENAME
+
+        if not mat_path.exists():
+            msg = (
+                run_result.error_message if run_result else None
+            ) or f"Result file not found: {mat_path}"
+            return TestResult(
+                model_id=test.model_id,
+                success=False,
+                error_message=msg,
+                statistics=stats,
+            )
+
+        diag_names = list(self.om_config.diagnostic_variables)
+        needed = compute_needed_variables(mat_path, test, diag_names)
+
+        mat_data = read_result_mat(mat_path, variable_names=needed)
+        if mat_data is None:
+            return TestResult(
+                model_id=test.model_id,
+                success=False,
+                error_message=f"Failed to parse: {mat_path}",
+                statistics=stats,
+            )
+
+        variables, diagnostics = extract_variables(mat_data, test, diag_names)
+        stats = fold_diagnostics_into_statistics(stats, diagnostics)
+        # The system's size, from the file omc generated with the result
+        # (`init_xml`): here, so the persistent workers, `--batch` and a
+        # `compare` of an earlier run all record it.
+        stats = with_system_size(stats, test_dir / self.INIT_XML_FILENAME)
+
+        unfinished = unfinished_result(test, mat_path, variables, diagnostics, stats)
+        if unfinished is not None:
+            return unfinished
+
+        return TestResult(
+            model_id=test.model_id,
+            success=True,
+            variables=variables,
+            diagnostics=diagnostics,
+            statistics=stats,
+        )
+
+    @classmethod
+    def result_names(cls, test_dir: Path) -> list[str] | None:
+        return result_files.mat_names(test_dir / cls.RESULT_MAT_FILENAME)
+
+    @classmethod
+    def result_series(cls, test_dir, names):
+        return result_files.mat_series(test_dir / cls.RESULT_MAT_FILENAME, names)
+
+    @classmethod
+    def live_result_path(cls, test_dir: Path) -> Path:
+        return test_dir / cls.RESULT_MAT_FILENAME