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

dstf/figures/decimate.py

@@ -0,0 +1,150 @@
+"""Largest-Triangle-Three-Buckets (LTTB) decimation for figure rendering.
+
+Used on every figure embed — the report page and the authoring tool share
+the budget — while the full-resolution arrays stay on disk in
+``comparison_data.json``. Decimation affects what the browser draws, not
+pass/fail scoring, stored baselines, or downstream tooling.
+
+LTTB preserves visual peaks/valleys far better than uniform striding
+by selecting the point in each bucket that forms the largest triangle
+with the previously kept point and the next bucket's centroid.
+
+Reference: Sveinn Steinarsson, "Downsampling Time Series for Visual
+Representation" (MSc thesis, 2013).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def bucket_boundaries(
+    n_in: int, n_out: int
+) -> tuple[NDArray[np.int64], NDArray[np.int64], NDArray[np.int64]]:
+    """Every LTTB bucket boundary at once, for ``3 <= n_out < n_in``.
+
+    Bucket ``i`` is ``[starts[i], ends[i])`` and the bucket after it — whose
+    centroid the triangle uses — is ``[ends[i], next_ends[i])``. Same floor
+    arithmetic the pre-hoist loop did, one array at a time.
+
+    ``lttb``'s guard leaves ``3 <= n_out < n_in``, so
+    ``bucket_size = (n_in - 2) / (n_out - 2)`` is strictly above 1 and
+    consecutive entries of ``b`` differ by at least one. Hence no bucket is
+    empty (``starts[i] < ends[i]``) and every next-bucket holds at least one
+    sample (``next_ends[i] - ends[i] >= 1``) — which is why ``lttb`` carries
+    no empty-bucket branch and no ``maximum(counts, 1)``.
+
+    ``ends`` needs no clamp: its largest entry is ``b[n_out - 2]``, and
+    ``(n_out - 2) * bucket_size`` is ``n_in - 2`` in exact arithmetic, so the
+    entry is ``n_in - 1`` when the float product rounds up to or past
+    ``n_in - 2`` and ``n_in - 2`` when it rounds below — never above
+    ``n_in - 1``. (Measured over every pair with ``4 <= n_in <= 1200``:
+    680,649 at ``n_in - 1``, 36,354 at ``n_in - 2``, none above.)
+
+    ``next_ends`` is the one boundary that does overshoot, and its clamp is
+    load-bearing: ``b[n_out - 1] >= n_in`` whenever ``bucket_size > 1``, and
+    clamping it to exactly ``n_in`` is what makes ``reduceat``'s last segment
+    — which runs to the end of the array — agree with the last next-bucket.
+
+    Lives here, called by both ``lttb`` and the test that sweeps these
+    claims, so the guard reads production's arithmetic rather than a copy.
+    """
+    bucket_size = (n_in - 2) / (n_out - 2)
+    b = np.floor(np.arange(n_out, dtype=np.float64) * bucket_size).astype(np.int64) + 1
+    return b[: n_out - 2], b[1 : n_out - 1], np.minimum(b[2:n_out], n_in)
+
+
+def lttb(
+    time: NDArray[np.float64],
+    values: NDArray[np.float64],
+    n_out: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Decimate ``(time, values)`` to at most ``n_out`` points via LTTB.
+
+    Returns the original arrays unchanged when ``len(time) <= n_out`` or
+    when ``n_out < 3`` (the algorithm requires at least first, last, and
+    one interior bucket). Empty inputs return empty outputs.
+
+    Bucket means come from ``np.add.reduceat``, which sums a segment in a
+    different order than ``np.mean``; the two differ by round-off. That
+    changes a pick only where candidate areas tie up to round-off: collinear
+    runs (every area is round-off, the other sample lies on the same line)
+    and equal-area candidates on stepped or boolean signals over a uniform
+    grid (the tie breaks to the other plateau). Either pick is a valid LTTB
+    choice of equal area; the difference is in the drawing, not the data.
+    """
+    n_in = len(time)
+    if n_in == 0:
+        return np.asarray([], dtype=np.float64), np.asarray([], dtype=np.float64)
+    if n_in != len(values):
+        raise ValueError(f"time and values length mismatch: {n_in} vs {len(values)}")
+    if n_out >= n_in or n_out < 3:
+        return np.asarray(time, dtype=np.float64), np.asarray(values, dtype=np.float64)
+
+    t = np.asarray(time, dtype=np.float64)
+    v = np.asarray(values, dtype=np.float64)
+
+    out_idx = np.empty(n_out, dtype=np.int64)
+    out_idx[0] = 0
+    out_idx[-1] = n_in - 1
+
+    starts, ends, next_ends = bucket_boundaries(n_in, n_out)
+    # Next-bucket means, one reduceat each. reduceat's last segment runs to
+    # the end of the array, which is where the last next-bucket ends
+    # (next_ends[-1] == n_in, since b[n_out - 1] >= n_in), so the two agree.
+    counts = next_ends - ends
+    avg_t = np.add.reduceat(t, ends) / counts
+    avg_v = np.add.reduceat(v, ends) / counts
+
+    a = 0
+    for i in range(n_out - 2):
+        bucket_start = int(starts[i])
+        bucket_end = int(ends[i])
+        ta, va = t[a], v[a]
+        seg_t = t[bucket_start:bucket_end]
+        seg_v = v[bucket_start:bucket_end]
+        area = np.abs((ta - avg_t[i]) * (seg_v - va) - (ta - seg_t) * (avg_v[i] - va))
+        chosen = bucket_start + int(np.argmax(area))
+        out_idx[i + 1] = chosen
+        a = chosen
+
+    return t[out_idx], v[out_idx]
+
+
+def decimate_pair(
+    time: list | NDArray,
+    values: list | NDArray,
+    n_out: int,
+) -> tuple[list, list]:
+    """LTTB that accepts/returns plain Python lists (template-context friendly)."""
+    if time is None or values is None:
+        return time, values
+    if not len(time) or not len(values):
+        return list(time), list(values)
+    t_out, v_out = lttb(
+        np.asarray(time, dtype=np.float64), np.asarray(values, dtype=np.float64), n_out
+    )
+    return t_out.tolist(), v_out.tolist()
+
+
+def decimate_band(
+    time: NDArray[np.float64],
+    lower: NDArray[np.float64],
+    upper: NDArray[np.float64],
+    n_out: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Decimate an envelope on ONE shared time axis.
+
+    LTTB picks the kept samples from ``upper``; ``lower`` is then read at
+    exactly those times. The kept times are grid nodes, so ``np.interp`` at
+    them returns the node values — no approximation, and the two edges can
+    never drift onto different x arrays.
+    """
+    t2, u2 = lttb(
+        np.asarray(time, dtype=np.float64), np.asarray(upper, dtype=np.float64), n_out
+    )
+    l2 = np.interp(
+        t2, np.asarray(time, dtype=np.float64), np.asarray(lower, dtype=np.float64)
+    )
+    return t2, l2, u2

dstf/figures/families.py

@@ -0,0 +1,289 @@
+"""Array families (DESIGN.md "Array families on a plot"; brief §3.9).
+
+Indexed names fold by their LAST integer index: ``pipe.T[3]`` and
+``pipe.medium[3].T`` each belong to a family; ``x[2,3]`` does not.
+``massPorts[4, 1].C[3]`` does, by its last index. One function, so the
+figure's legend, the Variables drawer's folded row and the folded criteria
+row agree on what a family is.
+
+A family is a DISPLAY fold, so it folds over what a person reads — the
+label, which for a UnitTests variable is the expression the model wrote.
+Callers pass a ``{name: label}`` mapping; the members stay names, because
+that is what everything else is keyed by.
+
+Two rules, and the caller says which by what it passes. A RESULT-FILE NAME
+(the label a variable has when it has no expression) folds by its last
+single-integer index and nothing else — result files spell names in ways no
+whitelist anticipates (``θ[1]``, ``pipe₊T[1]`` from Julia/MTK, ``T-wall[1]``,
+``$DER.x[1]``), and every one of them was a family before expressions
+existed. An EXPRESSION the model wrote is held to the strict shape below:
+it is text a person typed, and ``sum(pipe.Qs[1])`` folded with
+``sum(pipe.Qs[2])`` gives two quantities one legend entry, one colour ramp
+and a label naming a third thing neither of them is."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+
+_LAST_INDEX = re.compile(r"\[(\d+)\](?!.*\[\d+\])")
+#: A multi-dimensional index (``x[2,3]``) is not one array position.
+_MULTI_INDEX = re.compile(r"\[[^\]]*,[^\]]*\]")
+#: A Modelica variable name as a person TYPES one: identifiers (letters in
+#: any script, so ``θ[1]`` is one), dots and index brackets. A quoted
+#: identifier (``a.'b c'[2]``) is collapsed to one letter first, so its
+#: spaces and punctuation do not have to be allowed everywhere.
+_PLAIN_NAME = re.compile(r"^[^\W\d][\w.\[\]]*$")
+#: Modelica's Q-IDENT: a backslash escapes the next character, so
+#: ``'it\'s'`` is one identifier, not ``'it\'`` and a stray ``s'``.
+_QUOTED_ID = re.compile(r"'(?:[^'\\]|\\.)*'")
+#: An index of integers only, one or several (`[3]`, `[4, 1]`): a position
+#: in an array, however many dimensions. Collapsed before `_PLAIN_NAME`, so
+#: an expression that indexes a port two-dimensionally is still a plain name
+#: (`massPorts[4, 1].C[1]`). A slice (`[6, :]`) is not one: it stays and
+#: refuses the name. No space just inside the brackets, as `_LAST_INDEX`
+#: allows none: otherwise `x[1].C[ 2 ]` folded on its FIRST index.
+_INT_INDEX = re.compile(r"\[\d+(?:\s*,\s*\d+)*\]")
+#: ``der(...)``, and only that: a derivative IS an element of the array it
+#: differentiates. Any OTHER call is a reduction over the array — ``sum(...)``
+#: of two different slices is two quantities, not two elements of one.
+#:
+#: Indexed AFTER the call too (``der(x)[1]``): that is a plain indexed name
+#: of the derivative of an array, so ``der(x)[1]`` and ``der(x)[2]`` are two
+#: elements of one array and fold. ``der(x[1], 2)`` does NOT — a second
+#: derivative is a call of two arguments, and the index inside it belongs to
+#: the argument, not to what the call returns; it stays a family of one.
+_DER_CALL = re.compile(r"^der\((.*)\)(?:\[\d+\])*$")
+
+#: Four stops per hue, light to dark (Material 200 / 400 / 700 / 900). The
+#: first is DESIGN.md's accent ramp; a second family on a plot takes the
+#: next hue, and the list cycles. These are the default theme's: a figure
+#: reads its theme's ramps (`palette.py`), and a dark theme's lighten the
+#: four stops that sink into a dark plot.
+HUES: tuple[tuple[str, str, str, str], ...] = (
+    ("#90caf9", "#42a5f5", "#1976d2", "#0d47a1"),
+    ("#a5d6a7", "#66bb6a", "#388e3c", "#1b5e20"),
+    ("#ce93d8", "#ab47bc", "#7b1fa2", "#4a148c"),
+)
+
+
+def mask_quoted(text: str) -> str:
+    """``text`` with every character inside a quoted identifier replaced by
+    a letter, quotes kept, and the SAME length — so a position found in the
+    mask slices ``text``. A quoted identifier is one name: the ``[5]`` of
+    ``a.'x[5]'`` is no index and the dot of ``'a.b'.c`` no separator, and
+    a search that reads the mask cannot mistake them for either."""
+    return _QUOTED_ID.sub(lambda m: "'" + "q" * (len(m[0]) - 2) + "'", text)
+
+
+def _names_an_element(text: str) -> bool:
+    """Does ``text`` spell a variable, rather than compute one?
+
+    A plain name with any number of ``der(...)`` wrappers and leading
+    minus signs around it, in any order — ``-der(x[2])`` and
+    ``der(-x[2])`` are the same quantity and must answer the same. A
+    ``der(...)`` may itself be indexed (``der(x)[1]``, the derivative of an
+    array taken element by element). Everything else —
+    ``sum(core.Qs[6, :])``, ``cat(1, a, b)[2]``, ``abs(x[1])``,
+    ``der(x[1], 2)`` — is an expression: its value is not an element of the
+    array whose index it happens to end with.
+    """
+    while True:
+        if text.startswith("-"):
+            text = text[1:]
+            continue
+        inner = _DER_CALL.match(text)
+        if inner is None:
+            break
+        text = inner.group(1)
+    return bool(_PLAIN_NAME.match(_INT_INDEX.sub("[0]", _QUOTED_ID.sub("q", text))))
+
+
+def family_of(text: str, *, expression: bool = False) -> tuple[str, int] | None:
+    """``(family key, index)`` — the text with its last ``[integer]`` emptied
+    — or ``None`` when it names no element of an array.
+
+    ``expression=False`` (the default) reads ``text`` as a RESULT-FILE
+    NAME: anything with a single-integer last index is a family, and a
+    multi-dimensional index (``x[2,3]``) is not. ``massPorts[4, 1].C[3]``
+    is, by its last index: a multi-dimensional index refuses a family only
+    AFTER the last single one. This is the only rule a name ever meets — a
+    result file spells names the caller does not get to whitelist.
+
+    ``expression=True`` reads it as a label a person typed, and only a
+    plain indexed name qualifies (``pipe.T[3]``, ``der(pipe.T[3])``,
+    ``der(pipe.T)[3]``, ``pipe.medium[3].T``, ``a.'b c'[2]``, ``-x[1]``).
+    ``cat(1, a, b)[2]``, ``sum(core.Qs[6, :])``, ``sum(pipe.Qs[1])`` and
+    ``der(x[1], 2)`` are computations, not elements of an array — the
+    second derivative's index belongs to the ARGUMENT of a two-argument
+    call, and nothing here can say the call returns an element of it.
+    """
+    if expression and not _names_an_element(text):
+        return None
+    masked = mask_quoted(text)  # `a.'x[5]'` has no index; the key is `text`'s
+    m = _LAST_INDEX.search(masked)
+    if m is None:
+        return None
+    # Multi-dimensional AFTER the last single index (`a[1].b[2,3]`): the
+    # element's own position is two-dimensional, so it is no member of an
+    # `a` array. BEFORE it (`massPorts[4, 1].C[3]`) it is where the array
+    # sits, and the element is C's 3rd (3c ruling).
+    if _MULTI_INDEX.search(masked, m.end()):
+        return None
+    return text[: m.start()] + "[]" + text[m.end() :], int(m.group(1))
+
+
+def _labelled(name: str, labels: Mapping[str, str] | None) -> str:
+    return (labels or {}).get(name, name)
+
+
+def _family_of_member(name: str, labels: Mapping[str, str] | None):
+    """The family of what ``name`` READS as, under the rule its text earns:
+    a text that IS the name is a result-file name, anything else is a label
+    the model or the page composed."""
+    text = _labelled(name, labels)
+    return family_of(text, expression=text != name)
+
+
+def group_families(
+    names: Sequence[str],
+    labels: Mapping[str, str] | None = None,
+) -> list[tuple[str, list[str]]]:
+    """``(key, members)`` in order of first appearance; members by index.
+
+    The fold is over each name's LABEL (``labels`` maps name → label;
+    without it a name is its own label), and the members are the NAMES. A
+    label with no family leaves its name its own group under its own name —
+    never under the label, or two variables sharing one expression would
+    become one group.
+    """
+    groups: dict[str, list[tuple[int, str]]] = {}
+    for name in names:
+        fam = _family_of_member(name, labels)
+        key, index = fam if fam is not None else (name, 0)
+        groups.setdefault(key, []).append((index, name))
+    return [(key, [n for _, n in sorted(members)]) for key, members in groups.items()]
+
+
+def slice_text(indices: Sequence[int]) -> str:
+    """Modelica slice syntax, the end INCLUDED: an arithmetic run reads
+    ``1:4`` or ``1:5:16``; anything else is a comma list in which each
+    unbroken run of three or more reads as a range (``1:6,8:20`` — a family
+    with a gap) and every other index singly (``1,2,4``, ``1,3,5:8``).
+    :func:`parse_slice` reads it back."""
+    idx = sorted(indices)
+    if len(idx) == 1:
+        return str(idx[0])
+    step = idx[1] - idx[0]
+    if step > 0 and all(b - a == step for a, b in zip(idx, idx[1:])):
+        return f"{idx[0]}:{idx[-1]}" if step == 1 else f"{idx[0]}:{step}:{idx[-1]}"
+    parts: list[str] = []
+    i = 0
+    while i < len(idx):
+        j = i
+        while j + 1 < len(idx) and idx[j + 1] - idx[j] == 1:
+            j += 1
+        if j - i >= 2:
+            parts.append(f"{idx[i]}:{idx[j]}")
+            i = j + 1
+        else:
+            parts.append(str(idx[i]))
+            i += 1
+    return ",".join(parts)
+
+
+#: The most indices one Indices text may name: a typed ``1:999999999`` is
+#: refused before it is a list.
+MAX_INDICES = 100_000
+
+#: ASCII digits and nothing else Unicode calls one (``１``, ``٣``): `\d`
+#: takes those, and an index typed with them is a slip of the keyboard.
+_INT = re.compile(r"[+-]?[0-9]+")
+
+
+def parse_slice(text: str) -> list[int]:
+    """The indices ``text`` names, ascending — what an Indices field holds
+    (:func:`slice_text`'s syntax, read back): an index (``3``), a range
+    with its end INCLUDED (``1:5``), a stepped one (``1:5:20`` is 1, 6, 11,
+    16 — start:step:end, as Modelica writes it), and a comma list of those
+    in any order (``1:3,7,10:2:20``); spaces anywhere. The indices are the
+    result file's — any whole number from 0 — and which of them an array
+    HAS is its caller's to check: a zero-based array (``y[0]``) has a 0,
+    and a floor of 1 here refused the very text its field was filled with.
+
+    ``ValueError`` with the sentence to show for anything else: nothing
+    written, a part that is no index or range, a negative index, a step
+    below 1, a range that ends before it starts, an index written twice."""
+    parts = [part.strip() for part in text.split(",")]
+    if not any(parts):
+        raise ValueError(
+            "Indices is empty: write an index (3), a range (1:5), a stepped "
+            "range (1:5:20) or a list of those (1:3,7)."
+        )
+    runs: list[range] = []
+    for part in parts:
+        numbers = [n.strip() for n in part.split(":")]
+        if not 1 <= len(numbers) <= 3 or not all(_INT.fullmatch(n) for n in numbers):
+            raise ValueError(
+                f"{part!r} is not an index or a range: write 3, 1:5 or 1:5:20."
+            )
+        values = [int(n) for n in numbers]
+        first, last = values[0], values[-1]
+        step = values[1] if len(values) == 3 else 1
+        if first < 0 or last < 0:
+            raise ValueError(f"{part}: an index is not negative.")
+        if step < 1:
+            raise ValueError(f"{part}: the step is at least 1.")
+        if last < first:
+            raise ValueError(f"{part} ends before it starts.")
+        runs.append(range(first, last + 1, step))
+    count = sum(len(run) for run in runs)
+    if count > MAX_INDICES:
+        raise ValueError(f"{text.strip()} names {count:,} indices: too many.")
+    seen: set[int] = set()
+    for run in runs:
+        for index in run:
+            if index in seen:
+                raise ValueError(f"{index} is written twice.")
+            seen.add(index)
+    return sorted(seen)
+
+
+def family_label(
+    key: str,
+    members: Sequence[str],
+    labels: Mapping[str, str] | None = None,
+) -> str:
+    """``pipe.T[1:5:16]`` for a family of several; the one member's LABEL for
+    a family of one (``labels`` as in :func:`group_families`)."""
+    if len(members) == 1:
+        return _labelled(members[0], labels)
+    indices = [
+        fam[1] for m in members if (fam := _family_of_member(m, labels)) is not None
+    ]
+    # the fold marker, never a `[]` inside a quoted identifier (`a.'b[]'.x[]`)
+    at = mask_quoted(key).find("[]")
+    if at == -1:
+        return key
+    return key[:at] + f"[{slice_text(indices)}]" + key[at + 2 :]
+
+
+def _rgb(hex_color: str) -> tuple[int, int, int]:
+    return int(hex_color[1:3], 16), int(hex_color[3:5], 16), int(hex_color[5:7], 16)
+
+
+def ramp(hue: Sequence[str], n: int) -> list[str]:
+    """``n`` colours along the hue's four stops, light to dark; one colour is
+    the third stop (the hue's name shade)."""
+    if n == 1:
+        return [hue[2]]
+    out = []
+    for i in range(n):
+        pos = i * (len(hue) - 1) / (n - 1)
+        lo = min(int(pos), len(hue) - 2)
+        frac = pos - lo
+        a, b = _rgb(hue[lo]), _rgb(hue[lo + 1])
+        out.append(
+            "#" + "".join(f"{round(x + (y - x) * frac):02x}" for x, y in zip(a, b))
+        )
+    return out

dstf/figures/palette.py

@@ -0,0 +1,170 @@
+"""What a figure takes from a theme (D148): one named table per bundled
+theme, read by name wherever a figure is built.
+
+A figure's colours are literals, never CSS variables: the report's
+plotly.js and the tool's read a figure dict, not a stylesheet. Most of
+them carry meaning and are the same in every theme — the actual and the
+reference, a pass and a fail region, the error series, a grip
+(``plotly.py``). The ones HERE follow the theme:
+
+* the figure's chrome — a reference event's guide line, an open
+  criterion's ring and handle markers, the grey of a context series, a
+  marker's outline (the plot's own ground) and the tint of a region
+  drawn over the plot's whole height;
+* the colours that sink into a dark plot — the actual's event line, the
+  three overlays (soft check, another backend's run, a companion) and
+  the darkest stops of the array families' ramps;
+* the layout template: the plot's ground, grid, axes, legend, hover label
+  and toolbar.
+
+The default theme's template is ``None``: its plot is plotly.js's own
+defaults and its figure carries no ``layout.template`` key at all. A dark
+table's neutrals are its token table's (``reporting.theme``), as literals;
+``tests/test_themes.py`` pins the two equal.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from .families import HUES
+
+
+@dataclass(frozen=True)
+class Palette:
+    #: A reference event's dashed guide line.
+    reference_event: str
+    #: An open criterion's ring and its handle markers, and the ring's
+    #: fill — the same colour at a quarter, so the ring takes the pointer
+    #: over its whole area.
+    ring: str
+    ring_fill: str
+    #: A context series: the theme's ``text-muted``.
+    context: str
+    #: A soft-check overlay.
+    soft_check: str
+    #: An event of the ACTUAL: a solid guide line, a shade under the
+    #: actual's own blue.
+    actual_event: str
+    #: The overlay of another backend's run of the same test.
+    sibling: str
+    #: A companion overlay.
+    companion: str
+    #: A marker's outline: the plot's ground, so a checkpoint stands off
+    #: the line it sits on.
+    marker_outline: str
+    #: The fill of a region with no bounds of its own, drawn over the
+    #: plot's whole height (an event's time tolerance): muted text at 9 %.
+    span_fill: str
+    #: The array families' ramps, light to dark (:func:`~.families.ramp`).
+    hues: tuple[tuple[str, str, str, str], ...]
+    #: ``layout.template.layout``, or ``None`` for plotly.js's own defaults.
+    #: Its ``xaxis`` / ``yaxis`` reach EVERY axis of that letter — the
+    #: spectrum's and the error axes' too; whatever a figure sets itself
+    #: (an error axis's red ticks) wins over it. A figure takes a COPY.
+    template: dict | None = None
+
+
+#: The dark theme's neutrals, as its token table names them.
+_DARK = MappingProxyType(
+    {
+        "surface": "#1e1e1e",
+        "surface-hover": "#2a2a2a",
+        "border": "#484848",
+        "border-hairline": "#303030",
+        "text": "#e4e4e4",
+        "text-secondary": "#b8b8b8",
+        "text-muted": "#9e9e9e",
+    }
+)
+
+
+def _dark_axis() -> dict:
+    """One dict per axis letter: a copy of the template keeps whatever two
+    keys share, and a figure's x axis must not be its y axis."""
+    return {
+        "gridcolor": _DARK["border-hairline"],
+        "zerolinecolor": _DARK["border"],
+        "linecolor": _DARK["border"],
+        "tickcolor": _DARK["border"],
+        "tickfont": {"color": _DARK["text-secondary"]},
+        "title": {"font": {"color": _DARK["text-secondary"]}},
+    }
+
+
+PALETTES: Mapping[str, Palette] = MappingProxyType(
+    {
+        "default": Palette(
+            reference_event="#757575",
+            ring="#2e7d32",
+            ring_fill="rgba(46,125,50,0.25)",
+            context="#888888",
+            soft_check="#7B1FA2",
+            actual_event="#1976D2",
+            sibling="#1976D2",
+            companion="#388E3C",
+            marker_outline="white",
+            span_fill="rgba(117,117,117,0.09)",
+            hues=HUES,
+        ),
+        "dark": Palette(
+            # Each of these on the dark plot (#1e1e1e), default -> dark:
+            # the event line 3.6 -> 7.0, the ring 3.3 -> 7.1, the soft
+            # check 2.0 -> 4.7 (WCAG contrast).
+            reference_event="#a8a8a8",
+            ring="#66bb6a",
+            ring_fill="rgba(102,187,106,0.25)",
+            context=_DARK["text-muted"],
+            soft_check="#ba68c8",
+            # Series a person reads against each other, so 4.5:1: the
+            # actual's event line and the sibling overlay 3.6 -> 7.5 (the
+            # dark accent's blue), the companion 4.0 -> 8.3 — a green
+            # apart from the ring's, as the default's is.
+            actual_event="#64b5f6",
+            sibling="#64b5f6",
+            companion="#81c784",
+            marker_outline=_DARK["surface"],
+            span_fill="rgba(158,158,158,0.09)",
+            # The four stops under 2.2:1 on the dark plot, each raised in
+            # lightness at its own hue and saturation until it clears 3:1
+            # and still stands darker than the stop before it. The eight
+            # others are the default theme's.
+            hues=(
+                (*HUES[0][:3], "#1264e2"),
+                (*HUES[1][:3], "#237b2a"),
+                (*HUES[2][:2], "#a631d8", "#8a40e4"),
+            ),
+            template={
+                "paper_bgcolor": _DARK["surface"],
+                "plot_bgcolor": _DARK["surface"],
+                "font": {"color": _DARK["text"]},
+                "xaxis": _dark_axis(),
+                "yaxis": _dark_axis(),
+                "legend": {"font": {"color": _DARK["text"]}},
+                "hoverlabel": {
+                    "bgcolor": _DARK["surface-hover"],
+                    "bordercolor": _DARK["border"],
+                    "font": {"color": _DARK["text"]},
+                },
+                "modebar": {
+                    "bgcolor": "rgba(0,0,0,0)",
+                    "color": _DARK["text-muted"],
+                    "activecolor": _DARK["text"],
+                },
+            },
+        ),
+    }
+)
+
+
+def palette_of(theme: str) -> Palette:
+    """The palette of the bundled theme ``theme``; any other name is a
+    ``ValueError`` that says the bundled ones."""
+    try:
+        return PALETTES[theme]
+    except KeyError:
+        raise ValueError(
+            f"unknown theme {theme!r}: the bundled themes are {', '.join(PALETTES)}"
+        ) from None