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

dstf/comparison/registry.py

@@ -0,0 +1,230 @@
+"""Registries for comparison metrics and MetricTree combinators.
+
+The extension seam docs/extensibility.md promises for the Metric layer.
+Before this module the metric and combinator name spaces were closed
+if/elif chains duplicated across four files (``modes.resolve_mode``,
+``tree_spec.VALID_METRICS`` / ``_MODE_TO_METRIC``,
+``tree_eval._build_combinator`` / ``_METRIC_TO_MODE_KEY``,
+``reporting/schema_export._MODES``) — adding a metric meant editing all
+of them. Now each of those derives from the descriptors registered here,
+so a third-party metric only has to call :func:`register_metric`.
+
+Builtins register in :mod:`dstf.comparison.builtins`, imported by the
+package ``__init__`` — mirroring how ``backends`` self-registers its
+backends.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from ..backends.types import DatasetType
+from .sides import Sides
+from .summaries import summarize_default
+from .types import ScoreSummary, VariableComparison
+
+if TYPE_CHECKING:
+    from .handles import HandleEdit, RowPlace
+    from .metric_tree import Combinator
+    from .modes import ComparisonMode
+    from .seeds import SeedData
+    from .tree_spec import CombinatorSpec
+
+#: The metric a leaf/override falls back to when none is named. Also the
+#: one metric whose name is *absent* from the flat override dict (there is
+#: no ``{"mode": "nrmse"}`` in stored specs — no key means NRMSE).
+DEFAULT_METRIC = "nrmse"
+
+#: The metric a flat override with no ``mode`` gets under ``--default-points``
+#: instead (``modes.resolve_mode``).
+DEFAULT_POINTS_METRIC = "points"
+
+
+def unnamed_metrics() -> tuple[str, str]:
+    """The metrics an override that names no ``mode`` may be scored by: the
+    default, or ``points`` under ``--default-points``. What such an override
+    may carry is what either reads."""
+    return (DEFAULT_METRIC, DEFAULT_POINTS_METRIC)
+
+
+#: Default ``accepted_datasets`` — every backend produces time series today.
+TIME_SERIES_ONLY = frozenset({DatasetType.TIME_SERIES})
+
+
+@dataclass(frozen=True)
+class MetricDescriptor:
+    """Everything the framework needs to know about one leaf metric.
+
+    ``build`` takes the flat override dict (the ``variable_overrides``
+    payload shape, also used for a :class:`~.tree_spec.LeafSpec`'s params)
+    plus the resolved tolerance, and returns a ready-to-score mode.
+
+    ``score_direction`` says which way a better score runs: ``"lower"``
+    for error-like scores (NRMSE, point violations) and ``"higher"`` for
+    coverage-like ones (tube's in-band fraction). ``accepted_datasets``
+    declares which :class:`~dstf.backends.types.DatasetType` kinds the
+    metric can score — a leaf handed anything else hard-fails in
+    :func:`~.tree_eval._evaluate_leaf`.
+
+    ``accepts_quantity`` says the metric's ``quantity`` param names the
+    data it scores. For such a metric — and ONLY for such a metric — a
+    string ``quantity`` makes the evaluator resolve the value from the
+    run's statistics / diagnostics instead of a tracked trajectory, and
+    lets :func:`~.tree_spec._parse_leaf` default ``variable`` to the path.
+    Off by default: a metric that scores trajectories must keep scoring
+    trajectories, so an unrecognized ``quantity`` stays an inert param
+    rather than silently swapping that metric's data source.
+
+    ``summarize`` turns the mode's ``VariableComparison`` into the pill
+    text and criterion sentence; see :mod:`.summaries`.
+
+    ``edit_handle`` is the inverse of the mode's ``kind="handle"``
+    primitives: the raw leaf, the handle's local id and its dragged position
+    in, the new raw leaf out, :class:`~.handles.HandleEditError` for a drag
+    the leaf cannot take; see :mod:`.handles`. ``None`` for a metric no drag
+    edits (the builtins ``nrmse`` and ``event-timing``).
+
+    ``place_row`` is what a Ctrl+click on the plot adds to the metric's
+    table: the leaf with one more row, settled on the data it scores
+    (:class:`~.handles.RowPlace`); ``None`` for a metric with no rows.
+    ``row_noun`` says what that row is called for a leaf — "a point" — or
+    ``None`` where a click adds nothing to THAT leaf (a tube of constant
+    width); the editor's hint reads it.
+
+    ``seed`` gives a new leaf its first values from the data it will score
+    (the reference / actual series in, the params to add out), so a leaf
+    added with only a metric and a variable is valid and sensible; ``None``
+    for a metric valid bare (``nrmse``, ``points``, ``event-timing``). See
+    :mod:`.seeds`.
+
+    ``drawn_by_default`` says whether the Test page draws a closed criterion
+    of this metric that is not failing before its swatch is touched
+    (``range`` and ``scalar`` do not); a failing one draws regardless.
+    """
+
+    name: str
+    config_cls: type
+    build: Callable[[dict, Sides], ComparisonMode]
+    accepted_datasets: frozenset[DatasetType] = TIME_SERIES_ONLY
+    score_direction: Literal["lower", "higher"] = "lower"
+    accepts_quantity: bool = False
+    #: One leaf's verdict in words. The default is NRMSE-shaped; every
+    #: builtin supplies its own in :mod:`.builtins`.
+    summarize: Callable[[VariableComparison], ScoreSummary] = summarize_default
+    #: A drag on one of the mode's handles, as the new raw leaf.
+    edit_handle: Callable[[HandleEdit], dict] | None = None
+    #: Whether a closed criterion of this metric that is not failing draws on
+    #: the Test page until its swatch says otherwise (legend b). Off for
+    #: metrics whose drawing is a bound across the whole plot — range, scalar
+    #: — which would otherwise cover every plot they sit on. The open
+    #: criterion always draws, and a failing one draws by default.
+    drawn_by_default: bool = True
+    #: A new leaf's first values from the data it will score.
+    seed: Callable[[SeedData], dict] | None = None
+    #: A Ctrl+click on the plot, as the leaf with one more row.
+    place_row: Callable[[RowPlace], dict] | None = None
+    #: What that row is called for a leaf, or None where a click adds none.
+    row_noun: Callable[[dict], str | None] | None = None
+
+
+@dataclass(frozen=True)
+class CombinatorDescriptor:
+    """One MetricTree combinator: a name plus a spec → instance builder.
+
+    ``build`` reads whatever combinator-specific fields it needs off the
+    :class:`~.tree_spec.CombinatorSpec` (``k``, ``weights``, ...). The
+    *shape* validation of those fields stays in ``tree_spec`` at parse
+    time — this is dispatch only.
+    """
+
+    name: str
+    build: Callable[[CombinatorSpec], Combinator]
+
+
+# Insertion-ordered: registration order is the canonical presentation order
+# for the schema export, the reporter's mode-schema map, and the "valid: ..."
+# list in resolve_mode's error.
+_METRICS: dict[str, MetricDescriptor] = {}
+_COMBINATORS: dict[str, CombinatorDescriptor] = {}
+
+
+def register_metric(desc: MetricDescriptor) -> MetricDescriptor:
+    """Register a leaf metric. Raises on a duplicate name.
+
+    Duplicates are loud rather than last-writer-wins: two metrics sharing
+    a name would make spec parsing depend on import order.
+    """
+    if desc.name in _METRICS:
+        raise ValueError(f"metric {desc.name!r} is already registered")
+    _METRICS[desc.name] = desc
+    return desc
+
+
+def register_combinator(desc: CombinatorDescriptor) -> CombinatorDescriptor:
+    """Register a MetricTree combinator. Raises on a duplicate name."""
+    if desc.name in _COMBINATORS:
+        raise ValueError(f"combinator {desc.name!r} is already registered")
+    _COMBINATORS[desc.name] = desc
+    return desc
+
+
+def metric(name: str) -> MetricDescriptor | None:
+    """Return the descriptor for ``name``, or None if not registered."""
+    return _METRICS.get(name)
+
+
+def combinator(name: str) -> CombinatorDescriptor | None:
+    """Return the descriptor for ``name``, or None if not registered."""
+    return _COMBINATORS.get(name)
+
+
+def metric_names() -> frozenset[str]:
+    return frozenset(_METRICS)
+
+
+def combinator_names() -> frozenset[str]:
+    return frozenset(_COMBINATORS)
+
+
+def metrics() -> tuple[MetricDescriptor, ...]:
+    """All metric descriptors in registration order."""
+    return tuple(_METRICS.values())
+
+
+def summarize(vc: VariableComparison) -> ScoreSummary:
+    """The pill text and criterion for one leaf, by its mode's descriptor.
+
+    Any sentinel carrying a reason — a leaf config that could not build, an
+    empty-data failure — shows that reason instead of a numeric score there
+    is none of. Mode-agnostic on purpose: the flat variable_overrides path
+    emits the same shape. Uses ``vc.mode`` raw: the unknown-mode sentinel
+    has no mode, and "nrmse leaf" would name the wrong metric.
+    """
+    error = (vc.diagnostics or {}).get("error")
+    if error:
+        label = f"{vc.mode} leaf" if vc.mode else "leaf"
+        return ScoreSummary(
+            display="not scored", criterion=f"{label} not scored — {error}"
+        )
+    # A mode nothing is registered under — none at all, or a plug-in's that
+    # is not loaded — reads as the default summary does.
+    desc = metric(vc.mode)
+    fn = desc.summarize if desc is not None else summarize_default
+    return fn(vc)
+
+
+def combinators() -> tuple[CombinatorDescriptor, ...]:
+    """All combinator descriptors in registration order."""
+    return tuple(_COMBINATORS.values())
+
+
+def _reset_for_tests() -> None:
+    """Drop user registrations and restore the builtins — unit tests only."""
+    _METRICS.clear()
+    _COMBINATORS.clear()
+
+    from .builtins import register_builtins
+
+    register_builtins()

dstf/comparison/seeds.py

@@ -0,0 +1,281 @@
+"""A new criterion's first values, from the data it will score.
+
+A leaf of `range`, `tube`, `scalar` or `dominant-frequency` with only a
+`metric` and a `variable` is misconfigured or always fails: `range` wants a
+bound, `tube` a width mode, `scalar` a quantity, and `dominant-frequency`
+scores but FAILs "no peaks declared". So the tool seeds one when it is
+added or its metric is switched: a pure function of the reference series
+(else the actual one), cut to the criterion's window when it has one, per
+metric, registered on its :attr:`~.registry.MetricDescriptor.seed`.
+
+A seed lands in a spec file a person reads, so its values are short — but
+rounded AWAY from the data, at the leading digit of the margin it leaves:
+rounded to 6 significant digits, a range over 101325 +- 0.001 got
+``min_value == max_value`` and failed on the data it was seeded from. Where
+the short form would land back on the data, the value is left unrounded.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+from .algorithms import _compute_fft_spectrum, _find_top_n_peaks
+from .registry import metric as metric_descriptor
+
+#: The margin a seed leaves around the data, as a fraction of its span.
+SEED_MARGIN = 0.05
+#: ... and never less than this fraction of the data's magnitude: a reference
+#: stored at 7 significant digits is rounded coarser than 5% of a small span.
+SEED_MARGIN_FLOOR = 1e-6
+#: The widest relative window a peak is seeded with. Two bins around a peak
+#: at FFT bin 1 is +-200%, a window that matches anything; a peak whose two
+#: bins are wider (one in the lowest three bins) is not seeded at all.
+MAX_PEAK_TOLERANCE = 0.5
+
+
+@dataclass(frozen=True)
+class SeedData:
+    """The ``(time, values)`` a new criterion will score, either may be
+    missing."""
+
+    ref: tuple[np.ndarray, np.ndarray] | None
+    act: tuple[np.ndarray, np.ndarray] | None
+
+    def within(self, window: dict | None) -> SeedData:
+        """Both series cut to ``window``'s ``start`` / ``end`` (either may
+        be absent), ends included as the scorer's window includes them: a
+        windowed criterion is seeded from the samples it scores."""
+        if not window:
+            return self
+        # float(), as `parse_metric_tree` reads them: a hand-written
+        # ``"start": "2"`` parses, and compared raw raised UFuncTypeError.
+        start = float(window.get("start", -math.inf))
+        end = float(window.get("end", math.inf))
+
+        def cut(s: tuple[np.ndarray, np.ndarray] | None):
+            if s is None:
+                return None
+            keep = (s[0] >= start) & (s[0] <= end)
+            return s[0][keep], s[1][keep]
+
+        return SeedData(ref=cut(self.ref), act=cut(self.act))
+
+    def series(self) -> tuple[np.ndarray, np.ndarray] | None:
+        """The reference, else the actual; None when neither has a finite value."""
+        for s in (self.ref, self.act):
+            if s is not None and np.isfinite(s[1]).any():
+                return s
+        return None
+
+
+def _short(x: float) -> float:
+    return float(f"{float(x):.6g}")
+
+
+def _outward(x: float, margin: float, up: bool) -> float:
+    """``x`` rounded away from the data at the margin's leading digit, when
+    that short form still lies on ``x``'s far side; else ``x`` itself.
+    Readable where it can be, and never inside the data: 101325 +- 0.001
+    kept a 6-digit rounding's min == max, and a margin below 12 significant
+    digits of the value (1e5 +- 1e-11) rounded the 12-digit form back onto
+    the data."""
+    q = 10.0 ** math.floor(math.log10(margin))
+    n = math.ceil(x / q) if up else math.floor(x / q)
+    short = float(f"{n * q:.12g}")
+    return short if (short >= x if up else short <= x) else x
+
+
+def _span(v: np.ndarray) -> tuple[float, float, float]:
+    """The finite data's min, max and span; a flat series' span is its
+    magnitude (else 1), so a margin is never zero."""
+    finite = v[np.isfinite(v)]
+    lo, hi = float(finite.min()), float(finite.max())
+    span = hi - lo
+    if span <= 0.0:
+        span = abs(hi) or 1.0
+    return lo, hi, span
+
+
+def _margin(v: np.ndarray) -> float:
+    """5% of the finite data's span, and at least `SEED_MARGIN_FLOOR` of its
+    magnitude."""
+    lo, hi, span = _span(v)
+    # OilWater_PTHX's `STHX.tube.mediums[2].h`: seeded from a 7-digit
+    # reference as [130450.58, 130451.02], its float32 result reached 130451.03125.
+    return max(SEED_MARGIN * span, SEED_MARGIN_FLOOR * max(abs(lo), abs(hi)))
+
+
+def seed_range(data: SeedData) -> dict:
+    """Both bounds, the data's span plus `_margin` either side."""
+    s = data.series()
+    if s is None:
+        return {}
+    lo, hi, _ = _span(s[1])
+    m = _margin(s[1])
+    return {
+        "min_value": _outward(lo - m, m, up=False),
+        "max_value": _outward(hi + m, m, up=True),
+    }
+
+
+def seed_tube(data: SeedData) -> dict:
+    """A band `_margin` wide around the reference."""
+    s = data.series()
+    if s is None:
+        return {}
+    m = _margin(s[1])
+    return {"tube_width_mode": "band", "tube_abs": _outward(m, m, up=True)}
+
+
+def seed_scalar(data: SeedData) -> dict:
+    """The final value: within 1% of the baseline's where the seed reads
+    the reference, else between bounds 5% of its magnitude either side."""
+    s = data.series()
+    if s is None:
+        return {}
+    quantity = {"reduce": "final"}
+    # Not `data.ref is not None`: a reference with no finite sample (all
+    # NaN, or none inside the window) seeds from the actual, and a
+    # tolerance against it failed on its own data.
+    if s is data.ref:
+        return {"quantity": quantity, "tolerance_mode": "rel", "tolerance": 0.01}
+    final = float(s[1][np.isfinite(s[1])][-1])
+    half = SEED_MARGIN * (abs(final) or _span(s[1])[2])
+    return {
+        "quantity": quantity,
+        "min_value": _outward(final - half, half, up=False),
+        "max_value": _outward(final + half, half, up=True),
+    }
+
+
+def seed_dominant_frequency(data: SeedData) -> dict:
+    """The strongest peak of the data's spectrum, 5% wide or two bins,
+    whichever is wider. None when two bins are wider than
+    `MAX_PEAK_TOLERANCE` — a peak in the lowest three bins is a trend's
+    leakage at ~1/span, not a frequency: over TRANSFORM, 279 of 322 varying
+    variables have their strongest peak there. The leaf stays bare, and
+    scoring says to declare a peak."""
+    s = data.series()
+    if s is None:
+        return {}
+    freqs, spectrum = _compute_fft_spectrum(*s)
+    peaks = _find_top_n_peaks(freqs, spectrum, 1)
+    if not peaks:
+        return {}
+    f = peaks[0][0]
+    bin_width = float(freqs[1] - freqs[0])
+    # At least two bins wide: the bins follow the SPAN, so a peak seeded on
+    # a 10 s reference sits between the bins of a 9 s result, and matching
+    # needs a local maximum inside the window.
+    two_bins = 2.0 * bin_width / f
+    if two_bins > MAX_PEAK_TOLERANCE:
+        return {}
+    tol = max(SEED_MARGIN, two_bins)
+    return {
+        "peaks": [
+            {"freq": _short(f), "tolerance": _short(tol), "tolerance_mode": "rel"}
+        ]
+    }
+
+
+def seeded_leaf(metric: str, variable: str, data: SeedData) -> dict:
+    """``{"metric", "variable"}`` plus the metric's seed, if it has one."""
+    leaf = {"metric": metric, "variable": variable}
+    desc = metric_descriptor(metric)
+    if desc is None or desc.seed is None:
+        return leaf
+    return {**leaf, **desc.seed(data)}
+
+
+#: Diagnostics whose kind is known by name (K1): a count is scored exact, a
+#: time within 10%. A tiny model's CPUtime can end on a whole 0.0 or 1.0:
+#: read by its values alone it is a count, and a next run's 0.01 s fails.
+COUNTS = frozenset({"EventCounter"})
+TIMES = frozenset({"CPUtime"})
+
+
+def quantity_kind(
+    path: str, values: np.ndarray | None = None
+) -> Literal["count", "time"]:
+    """What kind of number ``path`` names (S5): a ``count`` is scored exact,
+    a ``time`` within 10%. A statistic is a time by its path — the
+    ``timing`` section, CPUtime, and the ``*_time`` / ``*_wall`` /
+    ``cpu_time*`` keys; every other number a backend records is a count,
+    whatever its type (a Dymola ``result_points`` can be written as a
+    float).
+
+    A diagnostic's summary (``CPUtime.final``) takes K1's rule: by name
+    when known, else a count when every finite sample of ``values`` is a
+    whole number. A top-level statistic given the run's samples of the
+    diagnostic it names (``CPUtime``, folded in from the diagnostics) is
+    that diagnostic's final and takes the same rule — the Statistics row
+    and the add form's ``X.final`` leaf are one kind."""
+    name, _, field = path.rpartition(".")
+    if not name and values is not None:
+        name, field = path, "final"
+    if name and "." not in name and field in ("final", "min", "max"):
+        if name in COUNTS:
+            return "count"
+        if name in TIMES:
+            return "time"
+        finite = values[np.isfinite(values)] if values is not None else np.array([])
+        whole = finite.size > 0 and bool(np.all(finite == np.round(finite)))
+        return "count" if whole else "time"
+    head = path.split(".", 1)[0]
+    last = path.rsplit(".", 1)[-1]
+    if (
+        head == "timing"
+        or last in TIMES
+        or last.endswith(("_time", "_wall"))
+        or last.startswith("cpu_time")
+    ):
+        return "time"
+    return "count"
+
+
+def seed_quantity(
+    path: str,
+    kind: Literal["count", "time"],
+    *,
+    into: str,
+    variable: str | None = None,
+) -> dict:
+    """A ``scalar`` criterion on the stored number ``path`` names:
+    ``tolerance 0 abs`` for a count and ``0.1 rel`` for a time. With
+    ``variable`` (a diagnostic's name) the leaf names it: parsed without
+    one, its variable becomes the quantity text, and its row reads
+    ``scalar · CPUtime.final``.
+
+    A time is seeded inside a ``warn`` when it lands in an ``and``
+    (``into``, the kind of the combinator it is added to): a run's CPU time
+    moves with the machine's load — under ``--parallel`` most of all — and
+    10% would fail a test whose model did not change. Anywhere else it is
+    bare: a ``warn`` child passes whatever it scores, so under an ``or`` or
+    a ``k-of-n`` it would pass its parent with nothing else passing. A
+    count stays bare: it only moves when the model does."""
+    count = kind == "count"
+    leaf: dict = {"metric": "scalar"}
+    if variable is not None:
+        leaf["variable"] = variable
+    leaf.update(
+        {
+            "quantity": path,
+            "tolerance": 0 if count else 0.1,
+            "tolerance_mode": "abs" if count else "rel",
+        }
+    )
+    if not count and into == "and":
+        return {"combinator": "warn", "children": [leaf]}
+    return leaf
+
+
+def seed_diagnostic(name: str, values: np.ndarray | None, *, into: str) -> dict:
+    """A criterion on the diagnostic ``name`` (the plan's K1): its stored
+    final through a quantity path, seeded by :func:`seed_quantity` at the
+    kind :func:`quantity_kind` reads from ``values``."""
+    path = f"{name}.final"
+    return seed_quantity(path, quantity_kind(path, values), into=into, variable=name)

dstf/comparison/sides.py

@@ -0,0 +1,158 @@
+"""A tolerance's two sides — the ONE place a number-or-pair is read or written.
+
+A spec holds a tolerance as a number (both sides equal) or as the pair
+``{"lower": a, "upper": b}``. Every scorer takes :class:`Sides`; a number
+``v`` is ``Sides(v, v)``, so a spec holding only numbers scores as it did
+before a pair existed. What the sides MEAN is the scorer's: ``actual −
+target`` must lie in ``[−lower, upper]``; in time, ``lower`` is how much
+earlier and ``upper`` how much later.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import numbers
+from dataclasses import dataclass
+from typing import TypeGuard
+
+
+@dataclass(frozen=True)
+class Sides:
+    lower: float
+    upper: float
+
+    @property
+    def equal(self) -> bool:
+        return self.lower == self.upper
+
+
+def _is_number(value: object) -> TypeGuard[int | float]:
+    """A finite real number that is not a bool: stricter than
+    ``float(value)``, which also takes ``True`` and the string ``"0.01"``,
+    and no stricter on a number — a numpy scalar is one. An int too large
+    for a float is not: it has no finite float."""
+    if isinstance(value, bool) or not isinstance(value, numbers.Real):
+        return False
+    try:
+        return math.isfinite(float(value))
+    except OverflowError:
+        return False
+
+
+def is_base_tolerance(value: object) -> bool:
+    """Whether ``value`` can be a test's BASE tolerance (the spec entry's or
+    the reference JSON's ``comparison.tolerance``, the project's): ONE finite
+    number. Not a pair — nrmse, the default metric, has one ceiling — and
+    not a bool, a string or a list, which ``float()`` took or raised on;
+    not NaN or an infinity, which every leaf then refused in its own words."""
+    return _is_number(value)
+
+
+def _as_json(value: object) -> str:
+    """``value`` in a refusal, cut to 60 characters: as the JSON file holds
+    it (``true``, ``NaN``, ``{"lower": …}``), not as Python spells it; its
+    ``repr`` only where JSON cannot write it."""
+    try:
+        text = json.dumps(value, allow_nan=True, ensure_ascii=False)
+    except (TypeError, ValueError):
+        text = repr(value)
+    if len(text) > 60:
+        text = text[:60] + "…"
+    return text
+
+
+def base_tolerance_refused(where: str, value: object) -> str:
+    """What a base tolerance that is not :func:`is_base_tolerance` is refused
+    with — a test's comparison's ``error_message``, a project's config
+    error: the rule, then where the value is written (``where``, in words)
+    and what it is (:func:`_as_json`). Where a pair belongs is said to a
+    dict alone: a string or a list was no attempt at one."""
+    rule = "the base tolerance must be a number"
+    if isinstance(value, dict):
+        rule += "; a lower/upper pair belongs on a criterion"
+    return f"{rule} ({where} is {_as_json(value)})"
+
+
+#: The keys of a pair, and of nothing else: what :func:`parse_sides` reads.
+PAIR_KEYS = ("lower", "upper")
+
+
+def parse_sides(value: object, what: str) -> Sides:
+    """``value`` as :class:`Sides`: a number is both sides, a dict whose keys
+    are exactly ``lower`` and ``upper`` is the pair, a :class:`Sides` is
+    itself. Anything else is a ``ValueError`` naming ``what`` and the value
+    (:func:`_as_json`).
+    No sign check: a negative side is not refused here, as a negative number
+    never was."""
+    if isinstance(value, Sides):
+        return value
+    if _is_number(value):
+        return Sides(float(value), float(value))
+    if isinstance(value, dict) and set(value) == set(PAIR_KEYS):
+        lower, upper = value["lower"], value["upper"]
+        if _is_number(lower) and _is_number(upper):
+            return Sides(float(lower), float(upper))
+    raise ValueError(
+        f'{what} must be a number or {{"lower": …, "upper": …}}, got {_as_json(value)}'
+    )
+
+
+def parse_number(value: object, what: str) -> float:
+    """``value`` as the ONE number a field without sides takes — a tube's
+    minimum width, a floor under both of its sides. Anything else — a
+    lower/upper pair, a string, a bool, a list, NaN or an infinity — is a
+    ``ValueError`` naming ``what`` and the value (:func:`_as_json`), the
+    way :func:`parse_sides` refuses what is no number or pair. No sign
+    check here either."""
+    if _is_number(value):
+        return float(value)
+    raise ValueError(f"{what} must be one number, got {_as_json(value)}")
+
+
+def as_written(sides: Sides) -> float | dict:
+    """``sides`` as data leaving Python (a tree view, a leaf's diagnostics):
+    the number when the sides are equal, else the pair. NOT how the tool
+    writes a spec — there the shape is the author's."""
+    if sides.equal:
+        return sides.upper
+    return {"lower": sides.lower, "upper": sides.upper}
+
+
+def sides_text(sides: Sides, fmt: str = ".3e") -> str:
+    """``sides`` in a sentence: the one number when equal (a minus as
+    U+2212; a zero reads as zero whatever its sign bit), else
+    :func:`signed_sides`."""
+    if sides.equal:
+        text = format(abs(sides.upper) if sides.upper == 0 else sides.upper, fmt)
+        return f"−{text[1:]}" if text.startswith("-") else text
+    return signed_sides(sides, fmt)
+
+
+def signed_sides(
+    sides: Sides, fmt: str = ".3e", *, scale: float = 1.0, unit: str = ""
+) -> str:
+    """``−lower / +upper`` (U+2212, as the report's other signs) — the
+    band's two edges as signed numbers, each ``scale``d and followed by
+    ``unit`` (``100`` and ``%`` for a relative pair), so a negative lower
+    side, whose edge lies above the target, reads ``+…``. A zero side reads
+    by its side, not its sign bit: ``-0.0`` is ``0.0``."""
+    lower = _signed(-sides.lower * scale, fmt, zero="−")
+    upper = _signed(sides.upper * scale, fmt, zero="+")
+    return f"{lower}{unit} / {upper}{unit}"
+
+
+def signed(value: float, fmt: str = ".3e") -> str:
+    """A deviation in a sentence: ``value`` with its sign always — ``+``, or
+    U+2212 for the minus, as :func:`signed_sides` writes an edge; a zero
+    reads ``+``."""
+    return _signed(value, fmt, zero="+")
+
+
+def _signed(value: float, fmt: str, *, zero: str) -> str:
+    """``value`` with its sign, the minus as U+2212; a zero takes ``zero``.
+    The sign only: an exponent's ``-`` stays as the format wrote it."""
+    text = format(abs(value) if value == 0 else value, f"+{fmt}")
+    if value == 0:
+        return zero + text[1:]
+    return f"−{text[1:]}" if text.startswith("-") else text