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

dstf/authoring/live_runs.py

@@ -0,0 +1,385 @@
+"""The runs whose result the Session does not have (D151): a test the queue
+is running, and one whose last run ended without finishing and left a
+partial result file. The Session's own tier — it holds the readers and
+opens the files; what their snapshots become is `authoring.live_rows`.
+
+A run that STARTS takes its test's result out of memory (D150: the run
+cleared it on disk). What the page was laid out by goes with it — the
+scored names its plots derive from, the tracked names, the labels — so the
+run's entry here keeps the comparison and the result it replaced, for the
+LAYOUT alone: no verdict and no sample of them is shown.
+
+While it runs, on a backend whose result file grows
+(``Capability.LIVE_RESULTS``), :meth:`LiveRuns.poll` reads the file once a
+second — for the names the open pages asked for (:meth:`LiveRuns.ask`), and
+with none, the time it has reached, which the queue panel's row says. One
+reader per run, polled from the UI loop: two tabs on one test share it.
+
+"In progress" is the queue's word, never the reader's: a finished file
+reads ``running`` too. An entry is in progress until the Session says its
+item ended (:meth:`LiveRuns.ended`); then it goes — or, where the run did
+not finish and its file holds a row, stays as a :class:`~.live_rows.Partial`,
+read by the size-based reader's partial read. A partial result is shown:
+nothing here hands it to the comparator or to the store.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..backends.common.live_mat import RUNNING, LiveMatReader
+from ..backends.common.mat_reader import ResultMatFile, read_mat_last_time
+from ..backends.pool import ItemState
+from ..backends.types import Capability, TestResult, VariableResult
+from ..discovery.spec_update import is_literal_variable
+from ..discovery.unit_tests import unit_test_variables
+from .live_rows import (
+    NOT_SCORED,
+    STARTING_WORD,
+    WAITING,
+    LiveTrace,
+    Partial,
+    how_ended,
+    progress,
+    run_revision,
+    spanned,
+    stopped_marker,
+)
+
+if TYPE_CHECKING:
+    from ..backends.pool import QueueItem
+    from ..comparison.types import TestComparison
+    from ..discovery.test_registry import TestModel
+    from .session import Session
+
+#: Polls a page's ask outlives: a page that stopped asking (closed, moved to
+#: another test) costs its names two more reads.
+ASK_LIFE = 2
+
+Series = tuple[np.ndarray, np.ndarray]
+
+
+def expected_result(test: TestModel) -> TestResult | None:
+    """What a test that never had a result is laid out by while its first
+    run is in progress, and after one that left a partial file: the
+    variables its model and its spec NAME — the UnitTests variables with
+    their expressions, then every ``variables`` entry that names one (a
+    pattern names none until a file is matched against it). No sample of
+    any: a layout, never a trace. None for a test that names none."""
+    named = {v.name: v.expression for v in unit_test_variables(test)}
+    for pattern in test.variable_patterns:
+        if is_literal_variable(pattern):
+            named.setdefault(pattern, "")
+    if not named:
+        return None
+    empty = np.empty(0)
+    return TestResult(
+        model_id=test.model_id,
+        success=True,
+        variables=[
+            VariableResult(
+                index=index, time=empty, values=empty, name=name, expression=text
+            )
+            for index, (name, text) in enumerate(named.items(), start=1)
+        ],
+    )
+
+
+@dataclass
+class _Run:
+    """One model's run with no result: in progress, or (``partial``) ended
+    without finishing."""
+
+    item: QueueItem
+    #: What the run replaced, for the page's layout.
+    comparison: TestComparison | None
+    result: TestResult | None
+    #: Whether the backend's result file grows while the run is in progress.
+    live: bool
+    trace: LiveTrace
+    #: The ``uirevision`` of this run's figures, its partial result's too.
+    revision: str
+    reader: LiveMatReader | None = None
+    #: The names each page asked for, and the poll it last asked at.
+    asked: dict[object, tuple[frozenset[str], int]] = field(default_factory=dict)
+    #: The reader's ``run`` whose file the pages were told can be read.
+    announced: int | None = None
+    partial: Partial | None = None
+    #: A partial file, its header parsed once for every name asked of it,
+    #: and its series by name; None is a name it lacks.
+    file: ResultMatFile | None = None
+    series: dict[str, Series | None] = field(default_factory=dict)
+
+    @property
+    def stop_time(self) -> float | None:
+        return self.item.test.stop_time
+
+
+class LiveRuns:
+    def __init__(
+        self, session: Session, emit: Callable[[str, frozenset[str]], None]
+    ) -> None:
+        """``emit(state, models)`` says a `queue` event the Session's
+        way: a run's file became readable, and its pages re-read what they
+        list of it."""
+        self._session = session
+        self._emit = emit
+        self._runs: dict[str, _Run] = {}
+        self._polls = 0
+        self._starts = 0
+
+    # -- the Session's calls ---------------------------------------------------
+
+    def started(self, item: QueueItem) -> None:
+        """``item`` started — called BEFORE the Session drops its test's
+        result. A test started again after a run that left none (a cancel)
+        keeps the layout that run kept; one that never had a result is laid
+        out by what it names (`expected_result`)."""
+        session = self._session
+        project = session.project
+        if project is None:
+            return
+        model_id = item.model_id
+        comparison = session.comparisons.get(model_id)
+        result = project.results.get(model_id)
+        before = self._runs.get(model_id)
+        if result is None or not result.success:
+            if before is not None:
+                comparison, result = before.comparison, before.result
+            else:
+                result = None  # a failed run's: it holds no variable
+            if result is None:
+                result = expected_result(item.test)
+        self._starts += 1
+        self._runs[model_id] = _Run(
+            item=item,
+            comparison=comparison,
+            result=result,
+            live=self._live(),
+            trace=self._trace(),
+            revision=run_revision(self._starts),
+        )
+
+    def ended(self, item: QueueItem) -> None:
+        """``item`` ended, as the QUEUE says — the reader's state is not
+        asked. A finished run's entry goes: the page shows its result. So
+        does an unfinished one's that left no row; one that left a partial
+        file stays, to be shown and never scored."""
+        model_id = item.model_id
+        run = self._runs.get(model_id)
+        if run is None or run.item is not item:
+            return
+        run.reader, run.trace, run.asked = None, self._trace(), {}
+        path = self._path(run)
+        reached = (
+            read_mat_last_time(path)
+            if item.state is not ItemState.FINISHED and path is not None
+            else None
+        )
+        if reached is None:
+            del self._runs[model_id]
+            return
+        outcome = item.run_result
+        run.partial = Partial(
+            how_ended(
+                cancelled=item.state is ItemState.CANCELLED,
+                timed_out=outcome is not None and outcome.timed_out,
+            ),
+            reached,
+            run.stop_time,
+        )
+
+    def clear(self) -> None:
+        """The project is closing: nothing of its runs is kept."""
+        self._runs.clear()
+
+    # -- what a page asks ------------------------------------------------------
+
+    def ask(self, model_id: str, page: object, names: Collection[str]) -> None:
+        """``page`` draws ``names`` of the running ``model_id``: the next
+        polls read them. Asked again every second it still does."""
+        run = self._runs.get(model_id)
+        if run is not None and run.partial is None and run.live:
+            run.asked[page] = (frozenset(names), self._polls)
+
+    def poll(self) -> None:
+        """Read every run in progress whose file grows, once: the names its
+        pages asked for, and how far it has got. On the UI loop."""
+        self._polls += 1
+        for model_id, run in list(self._runs.items()):
+            if run.partial is not None or not run.live:
+                continue
+            if run.reader is None:
+                path = self._path(run)
+                if path is None:
+                    continue  # its directory is not keyed yet
+                run.reader = LiveMatReader(path, max_rows=run.trace.cap)
+            run.asked = {
+                page: (names, at)
+                for page, (names, at) in run.asked.items()
+                if self._polls - at <= ASK_LIFE
+            }
+            names = frozenset().union(*(n for n, _ in run.asked.values()))
+            run.trace.take(run.reader.poll(sorted(names)))
+            if run.trace.run != run.announced and run.trace.state == RUNNING:
+                # This file's header is whole: its variables can be listed,
+                # and a file that replaced another's is listed again.
+                run.announced = run.trace.run
+                self._emit("live", frozenset({model_id}))
+
+    def polled(self, model_id: str) -> bool:
+        """Whether ``model_id`` is running with a live view."""
+        run = self._runs.get(model_id)
+        return run is not None and run.partial is None and run.live
+
+    def moved(self, model_id: str, name: str) -> bool:
+        """Whether the last poll brought ``name`` of ``model_id`` a sample."""
+        run = self._runs.get(model_id)
+        return run is not None and run.partial is None and run.trace.moved(name)
+
+    # -- what the Session reads ------------------------------------------------
+
+    def kept(
+        self, model_id: str
+    ) -> tuple[TestComparison | None, TestResult | None] | None:
+        """The comparison and the result ``model_id``'s run replaced — what
+        its page is laid out by while the Session has no result of it — or
+        None for a model with no entry here."""
+        run = self._runs.get(model_id)
+        return None if run is None else (run.comparison, run.result)
+
+    def word(self, model_id: str) -> str | None:
+        """What every criterion of ``model_id`` says in place of a verdict:
+        waiting while its run is in progress, not scored after one that did
+        not finish; None for a model with no entry here."""
+        run = self._runs.get(model_id)
+        if run is None:
+            return None
+        return WAITING if run.partial is None else NOT_SCORED
+
+    def partial(self, model_id: str) -> Partial | None:
+        run = self._runs.get(model_id)
+        return None if run is None else run.partial
+
+    def progress(self, item: QueueItem) -> str | None:
+        """``t = 42 / 100 s`` (or ``starting``) for a running ``item`` on a
+        backend with a live view; None on one without."""
+        if not self._live():
+            return None
+        run = self._runs.get(item.model_id)
+        if run is None or run.item is not item or run.partial is not None:
+            # Running by the queue's word, its start still on its way to
+            # the Session (a tick): nothing is read yet.
+            return STARTING_WORD
+        return progress(run.trace.state, run.trace.time, run.stop_time)
+
+    def names(self, model_id: str) -> tuple[str, ...] | None:
+        """The variables of ``model_id``'s file where the Session has no
+        result of it: a running test's growing file, once its header is
+        whole — the reader's own, from the header it reads the rows
+        through — and a partial result's, from the one parse its series
+        are read through. None before a header is whole, on a backend
+        without a live view, and for a model with no entry here."""
+        run = self._runs.get(model_id)
+        if run is None:
+            return None
+        if run.partial is not None:
+            file = self._file(run)
+            return None if file is None else file.names
+        if run.announced is None or run.reader is None:
+            return None
+        return run.reader.names
+
+    def series(self, model_id: str, name: str) -> tuple[Series | None, int] | None:
+        """What ``model_id``'s page draws as ``name``'s Actual in place of a
+        result's: ``(series, samples)`` — the samples read so far while its
+        run is in progress (none yet: empty; None on a backend without a
+        live view), a partial file's after one that did not finish
+        (``samples`` 0: the whole series, counted by whoever decimates it).
+        None for a model with no entry here."""
+        run = self._runs.get(model_id)
+        if run is None:
+            return None
+        if run.partial is None:
+            if not run.live:
+                return None, 0
+            # Empty before the first sample, never absent: the Actual trace
+            # keeps its place in the figure from the run's first second, so
+            # the legend's choices stay on the traces they were made on.
+            series = run.trace.series(name)
+            return series or (np.empty(0), np.empty(0)), run.trace.samples(name)
+        if name not in run.series:
+            # A name at a time, as the page asks — through one parse of the
+            # file's header, and with one time array for them all.
+            file = self._file(run)
+            read = None if file is None else file.series([name])
+            run.series[name] = (read or {}).get(name)
+        return run.series[name], 0
+
+    def dress(self, model_id: str, figure: dict, colour: str) -> dict:
+        """``figure`` as ``model_id``'s page draws it: one of its run's own
+        revision, the time axis spanning the whole run while a live view
+        grows into it, and after an unfinished run the marker where it
+        stopped, in ``colour``."""
+        run = self._runs.get(model_id)
+        if run is None or not run.live:
+            return figure
+        figure = spanned(figure, run.stop_time, run.revision)
+        if run.partial is None:
+            return figure
+        return stopped_marker(figure, run.partial, colour)
+
+    # -- internals ---------------------------------------------------------------
+
+    def _live(self) -> bool:
+        """Whether the project's backend writes a result file that grows
+        while a run is in progress."""
+        project = self._session.project
+        return (
+            project is not None
+            and Capability.LIVE_RESULTS in project.backend.capabilities
+        )
+
+    def _trace(self) -> LiveTrace:
+        project = self._session.project
+        budget = project.config.max_embedded_samples if project is not None else 0
+        return LiveTrace(cap=budget if budget and budget > 0 else 1000)
+
+    def _backend(self):
+        project = self._session.project
+        assert project is not None  # an entry exists only under a project
+        return project.backend
+
+    def _dir(self, run: _Run) -> Path | None:
+        """The run's directory, once it is keyed — a moment after its item
+        turns RUNNING, its last run's files cleared by then."""
+        project = self._session.project
+        key = run.item.test_key
+        if project is None or key is None:
+            return None
+        work_dir = project.config.work_dir
+        assert work_dir is not None  # resolved in Config.__post_init__
+        return work_dir / key
+
+    def _file(self, run: _Run) -> ResultMatFile | None:
+        """A partial result's file, opened once; None while it is not
+        there (its directory wiped for the next run)."""
+        if run.file is None:
+            path = self._path(run)
+            if path is not None:
+                run.file = ResultMatFile(path)
+        file = run.file
+        return file if file is not None and file.path.exists() else None
+
+    def _path(self, run: _Run) -> Path | None:
+        """The run's growing result file; None on a backend without one,
+        and until its directory is keyed."""
+        test_dir = self._dir(run)
+        if test_dir is None or not run.live:
+            return None
+        return type(self._backend()).live_result_path(test_dir)

dstf/authoring/needle.py

@@ -0,0 +1,127 @@
+"""The filter both drawers of the Test page ask (Tests and Variables): a
+needle as a substring, a glob or a typed regex, the regex held to a budget
+of its own CPU and of the UI loop's wall time."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from time import monotonic, thread_time
+
+from ..backends.types import is_glob_pattern
+
+#: Seconds of the searching thread's CPU (`thread_time`) ONE typed regex
+#: may search, over every name of one filter: the verdict "the pattern took
+#: too long" is the filter's own CPU, so waits for the GIL never make a
+#: plain pattern too long. An ordinary search costs ~2.5 us a name and
+#: reading that clock ~0.85 us more (a system call here; `monotonic` is
+#: ~0.075 us): on an idle machine TRANSFORM's largest result (76,992 names)
+#: takes ~0.27 s, and 0.25 s timed out a plain `T` over 100,000. 1 s leaves
+#: ~3.5x there; a loaded WSL2 host measured up to 0.99 s of thread CPU for
+#: the same filter, its `thread_time` counting time the host took the vCPU
+#: away. The clock is the thread's own because between searches the filter
+#: waits for the GIL on any busy thread of the tool (its overlay index
+#: json.loads for ~15 s after a page opens): in wall time those names took
+#: 0.4-0.9 s beside one or two such threads, two to three times their own
+#: CPU. Each search holds the GIL (``concurrent=False``): released, every
+#: search waited on a busy thread again, 0.3-0.9 ms a name beside one, and
+#: `T` on a wall-clock budget ran out after 1,200-3,600 names.
+#: The package times each search's ``timeout`` with C ``clock()``: on
+#: Linux and macOS the CPU time of the whole process, every thread summed;
+#: on Windows, wall time.
+REGEX_BUDGET = 1.0
+#: Seconds of WALL time (`monotonic`) the same filter may take. It runs on
+#: the UI event loop, so every tab is frozen for its wall time, which the
+#: CPU budget does not bound: beside a thread holding the GIL ~0.2 s at a
+#: time, a backtracking pattern froze the tool 17.4 s on 1 s of its own
+#: CPU, and a plain `T` over TRANSFORM's largest result took 10.7-20.5 s
+#: and never ran out. This is what bounds the freeze every tab sees. It is
+#: checked between searches: a search is given the smaller time left, but
+#: `regex` counts it on ``clock()`` — the process's CPU on Linux and macOS —
+#: so one search is bounded by the CPU left and can pass the wall time left.
+REGEX_WALL_BACKSTOP = 5 * REGEX_BUDGET
+
+
+def matcher(needle: str, *, regex: bool, case: bool) -> Callable[[str], bool]:
+    """What the filter box keeps. A regex (``.*`` on) searches; a glob (a
+    ``*`` or ``?`` in it) matches the WHOLE text with ``[ ]`` literal — the
+    rule a spec's ``variables`` list uses, so what you type here means what
+    it means there (`_glob`); anything else is a substring. ``regex.error``
+    for a bad regex, and ``TimeoutError`` from the returned closure once the
+    regex has searched `REGEX_BUDGET` seconds of its thread's CPU in all,
+    for the drawer to say.
+
+    A typed regex is the `regex` package's, never `re`'s: `re` has no
+    timeout, so a pattern that backtracks runs to its end (`^(a|aa)+$` over
+    60 a's and a ``b``: days), and `regex` stops a search at its
+    ``timeout``. Both hold the GIL for a whole search, `regex` because
+    ``concurrent=False`` asks it to, and the filter runs on the UI event
+    loop, so what bounds the freeze every tab sees is
+    `REGEX_WALL_BACKSTOP`'s wall time, not a worker thread; `REGEX_BUDGET`,
+    the filter's own CPU, decides a pattern that took too long. It is imported here, not at the
+    top: it comes with the ``[author]`` extra, and this module imports
+    without it. A glob is not left to a regex either — compiled to one,
+    ``*a*a*a*a*a*a*a*b`` over one 60-character name took over 20 s on the
+    UI event loop."""
+    flags = 0 if case else re.IGNORECASE
+    if not needle:
+        return lambda text: True
+    if regex:
+        import regex as regex_package
+
+        # unbounded: `(a{5000}){5000}` compiles for seconds, or out of memory
+        pattern = regex_package.compile(needle, 0 if case else regex_package.IGNORECASE)
+        # CPU, then wall; set at the first name, not at compile. The closure
+        # is one thread's: `thread_time` readings from two threads cannot be
+        # compared, and each drawer builds and uses it within one pass
+        # (`VariablesDrawer._build`, `TestsDrawer._kept`).
+        deadlines: list[float] = []
+
+        def search(text: str) -> bool:
+            cpu, wall = thread_time(), monotonic()
+            if not deadlines:
+                deadlines.extend((cpu + REGEX_BUDGET, wall + REGEX_WALL_BACKSTOP))
+            left = min(deadlines[0] - cpu, deadlines[1] - wall)
+            if left <= 0:
+                raise TimeoutError("the pattern took too long")
+            return pattern.search(text, timeout=left, concurrent=False) is not None
+
+        return search
+    if is_glob_pattern(needle):
+        return _glob(needle, flags)
+    folded = needle if case else needle.lower()
+    return lambda text: folded in (text if case else text.lower())
+
+
+def _glob(needle: str, flags: int) -> Callable[[str], bool]:
+    """``needle`` matched against the whole text as `_pattern_to_regex`'s
+    anchored regex matches it, without backtracking. Split on ``*``, each
+    piece is a fixed-length regex (``?`` is ``.``, everything else literal)
+    with no quantifier: the first must match at the start, the last at the
+    end, and each middle one is found left to right — the leftmost place
+    leaves the most text for the rest, so no other place is ever tried. A
+    ``*`` spans no newline and ``?`` matches none, as the regex's ``.``
+    does not (`test_the_glob_means_what_the_specs_regex_means`)."""
+    pieces = [
+        re.compile("".join("." if ch == "?" else re.escape(ch) for ch in p), flags)
+        for p in needle.split("*")
+    ]
+    if len(pieces) == 1:  # a ``?`` and no ``*``
+        (only,) = pieces
+        return lambda text: only.fullmatch(text) is not None
+    head, *middle, tail = pieces
+    width = len(needle.rsplit("*", 1)[1])  # the last piece's, one per character
+
+    def keep(text: str) -> bool:
+        start, end = head.match(text), len(text) - width
+        if start is None or end < start.end() or tail.fullmatch(text, end) is None:
+            return False
+        at = start.end()
+        for piece in middle:
+            found = piece.search(text, at, end)
+            if found is None or text.find("\n", at, found.start()) != -1:
+                return False
+            at = found.end()
+        return text.find("\n", at, end) == -1
+
+    return keep

dstf/authoring/picker_rows.py

@@ -0,0 +1,92 @@
+"""The add form's variable picker as data (the plan's K2): every name a
+criterion may score, in three sections — the plot's own series, every
+other variable of the result file, the diagnostics the run recorded —
+filtered on what a row reads as OR its result-file name, at most `CAP`
+rows. The shell draws them (`shell/picker.py`) and knows none of the
+rules, as the Variables drawer draws `variable_rows`."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+
+from ..backends.types import VariableText
+
+#: The drawer's cap (`variables_drawer.ROWS`): a result of 76,992 names
+#: drew 76,992 rows otherwise.
+CAP = 200
+ON_PLOT, OTHER, DIAGNOSTICS = "On this plot", "Other variables", "Diagnostics"
+SECTIONS = (ON_PLOT, OTHER, DIAGNOSTICS)
+
+
+@dataclass(frozen=True)
+class PickRow:
+    name: str  #: the result-file name — what a leaf is written against
+    text: str  #: what it reads as in the test's scope, else the name
+    section: str
+    #: the plain label (`VariableText.label`): what the row shows, the
+    #: muted name beside it
+    label: str
+
+
+@dataclass(frozen=True)
+class Picked:
+    sections: list[tuple[str, list[PickRow]]]
+    shown: int
+    total: int
+
+    @property
+    def capped(self) -> str | None:
+        """The line under a capped list, else None."""
+        if self.shown >= self.total:
+            return None
+        return f"Showing {self.shown} of {self.total:,} — narrow the search"
+
+
+def picker_rows(
+    *,
+    on_plot: Sequence[str],
+    names: Sequence[str],
+    diagnostics: Sequence[str],
+    texts: Mapping[str, VariableText],
+    keep: Callable[[str], bool],
+    cap: int = CAP,
+) -> Picked:
+    """The sections in the order On this plot / Other variables /
+    Diagnostics, each name once (in the first section that has it); an
+    empty section is absent. ``names`` is every name of the result file
+    (`Session.variable_names`); ``texts`` the test's
+    (`Session.variable_texts`), a name it lacks reading as itself;
+    ``diagnostics`` what the run RECORDED as
+    one — each is listed there and only there, whether or not the file
+    listing names it too (a Dymola file holds `CPUtime` as a variable),
+    unless the plot draws it: a diagnostic on the plot is listed under On
+    this plot, as every series of the plot is.
+    ``keep`` is `needle.matcher`'s closure: its ``TimeoutError`` reaches
+    the caller, which says it."""
+    first = list(dict.fromkeys(on_plot))
+    plotted = set(first)
+    diag = [d for d in dict.fromkeys(diagnostics) if d not in plotted]
+    taken = plotted | set(diag)
+    groups = (
+        (ON_PLOT, first),
+        (OTHER, [n for n in dict.fromkeys(names) if n not in taken]),
+        (DIAGNOSTICS, diag),
+    )
+    out: list[tuple[str, list[PickRow]]] = []
+    total = shown = 0
+    for title, members in groups:
+        rows = []
+        for name in members:
+            entry = texts.get(name)
+            text = entry.text if entry is not None else name
+            if not (keep(text) or (text != name and keep(name))):
+                continue
+            total += 1
+            if shown < cap:
+                label = entry.label if entry is not None else name
+                rows.append(PickRow(name, text, title, label))
+                shown += 1
+        if rows:
+            out.append((title, rows))
+    return Picked(out, shown, total)