quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/errors.py

@@ -0,0 +1,246 @@
+"""Error propagation. Ports of MATLAB +utilities/error*.m.
+
+Scalar uncertainty combination (quadrature) plus the general ``error_prop``
+driver (first-order Taylor + Monte Carlo). Pure functions.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = [
+    "error_add",
+    "error_div",
+    "error_func",
+    "error_mul",
+    "error_prop",
+]
+
+_EPS = 2.220446049250313e-16  # MATLAB eps
+
+
+def error_add(a: float, da: float, b: float, db: float) -> tuple[float, float]:
+    """a + b with quadrature error sqrt(da^2 + db^2)."""
+    return a + b, math.sqrt(da**2 + db**2)
+
+
+def error_mul(a: float, da: float, b: float, db: float) -> tuple[float, float]:
+    """a * b with relative quadrature error."""
+    val = a * b
+    rel_a = da / max(abs(a), _EPS)
+    rel_b = db / max(abs(b), _EPS)
+    return val, abs(val) * math.sqrt(rel_a**2 + rel_b**2)
+
+
+def error_div(a: float, da: float, b: float, db: float) -> tuple[float, float]:
+    """a / b with relative quadrature error."""
+    val = a / b
+    rel_a = da / max(abs(a), _EPS)
+    rel_b = db / max(abs(b), _EPS)
+    return val, abs(val) * math.sqrt(rel_a**2 + rel_b**2)
+
+
+def error_func(func: Callable[[float], float], a: float, da: float) -> tuple[float, float]:
+    """Propagate da through a 1-arg function via central-difference derivative."""
+    val = func(a)
+    h = max(abs(a) * 1e-7, 1e-10)
+    dfdx = (func(a + h) - func(a - h)) / (2.0 * h)
+    return val, abs(dfdx) * da
+
+
+# ════════════════════════════════════════════════════════════════════════════
+#  errorProp — propagate uncertainties through an arbitrary function
+# ════════════════════════════════════════════════════════════════════════════
+
+
+def error_prop(
+    func: Callable[..., Any],
+    values: ArrayLike,
+    errors: ArrayLike,
+    *,
+    method: str = "linear",
+    n_samples: int = 10000,
+    correlated: ArrayLike | None = None,
+    confidence: float = 0.95,
+) -> dict[str, Any]:
+    """Propagate uncertainties through an arbitrary function. Port of errorProp.m.
+
+    ``func`` takes N scalar (or array) arguments and returns a scalar or vector.
+    ``values`` / ``errors`` are length-N sequences: the nominal inputs and their
+    1-sigma uncertainties.
+
+    Returns a dict with keys:
+      * ``value``     — ``func(*values)`` at the nominal inputs (float or ndarray)
+      * ``error``     — propagated 1-sigma uncertainty (matches ``value`` shape)
+      * ``rel_error`` — ``error / max(|value|, eps)``
+      * ``formula``   — readable variance expression (``linear`` only; ``""`` for MC)
+      * ``ci``        — ``(lo, hi)`` confidence interval (``montecarlo`` only; else None)
+      * ``partials``  — flat ndarray of partial derivatives (``linear`` only; else None)
+
+    Methods:
+      * ``"linear"`` (default) — first-order Taylor with the *full* covariance
+        matrix, so ``correlated`` correlations are honoured; supports
+        vector-valued ``func`` (element-wise error).
+      * ``"montecarlo"`` — draw the (optionally correlated) input distribution via
+        a Cholesky factor and report the empirical std + percentile CI. Scalar
+        inputs only. Seeded (42) for reproducibility, but NOT bit-for-bit equal to
+        MATLAB's RNG — invariants hold; exact draws differ (see golden-tests rule).
+    """
+    if method not in ("linear", "montecarlo"):
+        raise ValueError(f'method must be "linear" or "montecarlo", got "{method}"')
+
+    vals = _to_inputs(values)
+    errs = _to_inputs(errors)
+    n = len(vals)
+    if len(errs) != n:
+        raise ValueError("values and errors must have the same number of elements")
+
+    if correlated is None:
+        corr = np.eye(n)
+    else:
+        corr = np.asarray(correlated, dtype=float)
+        if corr.shape != (n, n):
+            raise ValueError(
+                f"correlated must be [{n}x{n}], got {corr.shape[0]}x{corr.shape[1]}"
+            )
+
+    nom = np.asarray(func(*vals), dtype=float)
+    if method == "linear":
+        return _propagate_linear(func, vals, errs, corr, nom, n)
+    return _propagate_mc(func, vals, errs, corr, nom, n, n_samples, confidence)
+
+
+def _to_inputs(arg: ArrayLike) -> list[Any]:
+    """Normalise to a length-N list of per-variable inputs (MATLAB ``num2cell``).
+
+    A list/tuple is kept as-is (each element is one variable, scalar or array). A
+    bare numeric array is split along its first axis into N scalar variables.
+    """
+    if isinstance(arg, (list, tuple)):
+        return list(arg)
+    a = np.asarray(arg, dtype=float)
+    if a.ndim == 0:
+        return [float(a)]
+    return [a[i] for i in range(a.shape[0])]
+
+
+def _propagate_linear(
+    func: Callable[..., Any],
+    values: list[Any],
+    errors: list[Any],
+    corr: NDArray[np.float64],
+    nom: NDArray[np.float64],
+    n: int,
+) -> dict[str, Any]:
+    """First-order Taylor propagation with the full covariance matrix."""
+    partials: list[NDArray[np.float64]] = []
+    for i in range(n):
+        xi = np.asarray(values[i], dtype=float)
+        # Step size: relative if possible, absolute fallback (matches MATLAB).
+        h = np.asarray(np.maximum(np.abs(xi) * 1e-7, 1e-10), dtype=float)
+        fwd = list(values)
+        bwd = list(values)
+        fwd[i] = values[i] + h
+        bwd[i] = values[i] - h
+        f_fwd = np.asarray(func(*fwd), dtype=float)
+        f_bwd = np.asarray(func(*bwd), dtype=float)
+        partials.append(np.asarray((f_fwd - f_bwd) / (2.0 * h), dtype=float))
+
+    # Variance via full covariance: var_f = sum_ij dfi*dfj*corr_ij*sigma_i*sigma_j.
+    var_f = np.zeros(nom.shape, dtype=float)
+    for i in range(n):
+        for j in range(n):
+            cov_ij = corr[i, j] * np.asarray(errors[i], dtype=float) * np.asarray(
+                errors[j], dtype=float
+            )
+            var_f = np.asarray(var_f + partials[i] * partials[j] * cov_ij, dtype=float)
+
+    prop_error = np.asarray(np.sqrt(np.maximum(var_f, 0.0)), dtype=float)
+    rel_err = np.asarray(prop_error / np.maximum(np.abs(nom), _EPS), dtype=float)
+    partials_out = np.concatenate(
+        [np.atleast_1d(np.asarray(p, dtype=float)).ravel() for p in partials]
+    )
+    return {
+        "value": _unwrap(nom),
+        "error": _unwrap(prop_error),
+        "rel_error": _unwrap(rel_err),
+        "formula": _build_formula(partials, errors, n),
+        "ci": None,
+        "partials": partials_out,
+    }
+
+
+def _build_formula(partials: list[NDArray[np.float64]], errors: list[Any], n: int) -> str:
+    """Readable ``sigma_f^2 = ...`` string (replicates errorProp's scalar/vector forms)."""
+    parts: list[str] = []
+    for i in range(n):
+        p = np.asarray(partials[i], dtype=float)
+        e = np.asarray(errors[i], dtype=float)
+        if p.size == 1:
+            parts.append(f"(df/dx{i + 1}={float(p):.4g})^2*({float(e):.4g})^2")
+        else:
+            parts.append(f"(df/dx{i + 1})*^2*(sigma{i + 1})^2 [vector]")
+    return "sigma_f^2 = " + " + ".join(parts)
+
+
+def _propagate_mc(
+    func: Callable[..., Any],
+    values: list[Any],
+    errors: list[Any],
+    corr: NDArray[np.float64],
+    nom: NDArray[np.float64],
+    n: int,
+    n_samples: int,
+    confidence: float,
+) -> dict[str, Any]:
+    """Monte Carlo propagation (scalar inputs only); seeded but not RNG-identical."""
+    for v in values:
+        if np.asarray(v, dtype=float).size != 1:
+            raise ValueError(
+                "Monte Carlo method requires scalar inputs; use method='linear' "
+                "for vector inputs"
+            )
+    sigmas = np.asarray([float(np.asarray(e, dtype=float)) for e in errors], dtype=float)
+    means = np.asarray([float(np.asarray(v, dtype=float)) for v in values], dtype=float)
+
+    # Covariance = diag(sigma) * corr * diag(sigma); symmetrise then Cholesky.
+    cov = np.asarray(corr * np.outer(sigmas, sigmas), dtype=float)
+    cov = np.asarray((cov + cov.T) / 2.0, dtype=float)
+    try:
+        chol = np.linalg.cholesky(cov)
+    except np.linalg.LinAlgError:
+        # Not positive definite → fall back to the uncorrelated diagonal.
+        chol = np.diag(sigmas)
+
+    rng = np.random.default_rng(42)
+    z = rng.standard_normal((n, n_samples))
+    samples = means[:, None] + chol @ z
+    f_samples = np.asarray(
+        [float(func(*samples[:, s])) for s in range(n_samples)], dtype=float
+    )
+
+    mc_mean = float(np.mean(f_samples))
+    mc_std = float(np.std(f_samples, ddof=1))
+    rel_err = mc_std / max(abs(mc_mean), _EPS)
+    alpha = 1.0 - confidence
+    lo = float(np.percentile(f_samples, 100.0 * alpha / 2.0))
+    hi = float(np.percentile(f_samples, 100.0 * (1.0 - alpha / 2.0)))
+    return {
+        "value": _unwrap(nom),
+        "error": mc_std,
+        "rel_error": rel_err,
+        "formula": f"Monte Carlo (N={n_samples}, conf={confidence * 100:.0f}%)",
+        "ci": (lo, hi),
+        "partials": None,
+    }
+
+
+def _unwrap(a: NDArray[np.float64]) -> float | NDArray[np.float64]:
+    """0-d array → python float; otherwise return the array unchanged."""
+    arr = np.asarray(a, dtype=float)
+    return float(arr) if arr.ndim == 0 else arr

quantized/calc/figure.py

@@ -0,0 +1,417 @@
+"""Publication figure rendering via matplotlib. Pure layer: data in -> bytes.
+
+Renders a clean publication-style figure (white background, vector by default)
+to PDF / SVG (vector) or PNG / TIFF (raster, at a chosen DPI). Server-side so the
+browser gets a real vector file — the architecture's vector-by-default export
+preference; raster formats are available for journals that demand them. TIFF
+output goes through Pillow (a matplotlib dependency). matplotlib is imported here
+only (the heavy import is lazy at the route boundary).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless: render to a buffer, never to a display
+
+import matplotlib.pyplot as plt  # noqa: E402  (must follow matplotlib.use)
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from quantized.calc.figure_hitmap import collect_map as _collect_map_impl  # noqa: E402
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_overrides import _apply_overrides, _validate_overrides  # noqa: E402
+from quantized.calc.figure_scale import apply_axis_scale, resolve_axis_scale  # noqa: E402
+from quantized.calc.figure_styles import FigureStyle, figure_style  # noqa: E402
+from quantized.calc.figure_ticks import apply_tick_formats  # noqa: E402
+
+__all__ = ["draw_series_axes", "render_figure", "style_rc"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+_LINESTYLE = {"solid": "-", "dashed": "--", "dotted": ":"}
+# Fixed fill translucency for MAIN #13 (fill under/between curves) — matches
+# the screen side's `uplotFill.ts` FILL_ALPHA_PCT (25%) so an exported figure
+# reads the same as its on-screen counterpart.
+_FILL_ALPHA = 0.25
+
+
+def _plot_kwargs(
+    default_lw: float, default_marker_size: float, spec: Mapping[str, Any] | None
+) -> dict[str, Any]:
+    """Translate a per-series style spec (color/width/line/marker[/marker_size])
+    into matplotlib ``plot`` kwargs, so the export matches the on-screen styling.
+    ``default_marker_size`` is the active preset's calibrated marker size,
+    used only when a marker is requested without an explicit per-series size."""
+    kw: dict[str, Any] = {"linewidth": default_lw}
+    if not spec:
+        return kw
+    color = spec.get("color")
+    if color:
+        kw["color"] = color
+    width = spec.get("width")
+    if width is not None:
+        kw["linewidth"] = width
+    line = spec.get("line")
+    if line in _LINESTYLE:
+        kw["linestyle"] = _LINESTYLE[line]
+    if spec.get("marker"):
+        kw["marker"] = "o"
+        kw["markersize"] = spec.get("marker_size") or default_marker_size
+    return kw
+
+
+def _apply_fill(
+    ax: Any,
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    series: Sequence[tuple[str, ArrayLike]],
+    idx: int,
+    spec: Mapping[str, Any] | None,
+    color: Any,
+) -> None:
+    """Fill under (to a zero baseline) or between this series and another
+    plotted one (MAIN #13), via matplotlib ``fill_between`` -- the export
+    counterpart of the screen's native uPlot fill/band mechanism. ``color``
+    is the series' OWN drawn line colour (whatever ``ax.plot`` resolved to,
+    explicit or matplotlib's auto cycle) -- a fill is always derived from it,
+    never a separately stored colour. ``spec["fill"]["vs"]`` is already
+    resolved to a DISPLAY POSITION within ``series`` by
+    ``calc.plotting.resolve_style_channels`` -- this function never sees a
+    raw channel index."""
+    if not spec:
+        return
+    fill = spec.get("fill")
+    if fill == "under":
+        ax.fill_between(xv, yv, 0.0, color=color, alpha=_FILL_ALPHA)
+    elif isinstance(fill, Mapping):
+        vs = fill.get("vs")
+        if isinstance(vs, int) and 0 <= vs < len(series) and vs != idx:
+            other = np.asarray(series[vs][1], dtype=float)
+            n = min(len(xv), len(yv), len(other))
+            if n > 0:
+                ax.fill_between(xv[:n], yv[:n], other[:n], color=color, alpha=_FILL_ALPHA)
+
+
+def _draw_color_scatter(
+    fig: Any,
+    ax: Any,
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    label: str,
+    spec: Mapping[str, Any],
+    st: FigureStyle,
+) -> Any:
+    """Colour-mapped scatter (MAIN #14): each point coloured by a THIRD
+    channel's value -- ``spec["color_by"]``, already resolved by
+    ``calc.plotting.resolve_style_channels`` to a concrete per-row array (this
+    module never sees a raw channel index). Replaces the normal line draw
+    entirely for this series -- screen-side parity: ``uplotOpts.ts`` hides the
+    native line/points the same way whenever a series' ``colorBy`` is set.
+    Adds a colourbar so the mapping is legible. Returns the ``PathCollection``
+    artist (for the figure-hitmap element collector)."""
+    z = np.asarray(spec["color_by"], dtype=float)
+    n = min(len(xv), len(yv), len(z))
+    size = float(spec.get("marker_size") or st.marker_size) ** 2
+    sc = ax.scatter(
+        xv[:n], yv[:n], c=z[:n], cmap=str(spec.get("colormap") or "viridis"), s=size, label=label
+    )
+    fig.colorbar(sc, ax=ax)
+    return sc
+
+
+def style_rc(st: FigureStyle, ov: Mapping[str, Any]) -> dict[str, Any]:
+    """The rc-param dict a preset (+ optional font/tick overrides) resolves to.
+
+    Scoped to one render via ``matplotlib.rc_context`` by the callers (the
+    single-figure renderer below and the page composer in ``figure_page``).
+    The named font is given a generic fallback so matplotlib stays silent when
+    Helvetica/Arial/Times aren't installed on the host.
+    """
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    font_size = float(ov.get("font_size", st.font_size))
+    font_name = str(ov.get("font_name", st.font_name))
+    tick_dir = str(ov.get("ticks", {}).get("dir", st.tick_dir))
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [font_name, fallback],
+        "font.size": font_size,
+        "axes.labelsize": font_size,
+        "axes.titlesize": float(ov.get("title_size", st.title_font_size)),
+        "xtick.labelsize": font_size,
+        "ytick.labelsize": font_size,
+        "xtick.direction": tick_dir,
+        "ytick.direction": tick_dir,
+        # Mirror ticks onto the top/right spines whenever the box is drawn
+        # (the journal "closed box, inward ticks on all four sides" look) --
+        # matplotlib's own default leaves top/right bare even with the full
+        # rectangular border, which reads as an unfinished box.
+        "xtick.top": st.box_on,
+        "ytick.right": st.box_on,
+    }
+    tick_len = ov.get("ticks", {}).get("len")
+    if tick_len is not None:
+        rc["xtick.major.size"] = float(tick_len)
+        rc["ytick.major.size"] = float(tick_len)
+    return rc
+
+
+def draw_series_axes(
+    fig: Any,
+    ax: Any,
+    xv: NDArray[np.float64],
+    series: Sequence[tuple[str, ArrayLike]],
+    *,
+    st: FigureStyle,
+    ov: Mapping[str, Any],
+    x_log: bool = False,
+    y_log: bool = False,
+    x_scale: str | None = None,
+    y_scale: str | None = None,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    series_styles: Sequence[Mapping[str, Any] | None] | None = None,
+    x_fmt: Mapping[str, Any] | None = None,
+    y_fmt: Mapping[str, Any] | None = None,
+) -> list[Any]:
+    """Plot ``series`` into an EXISTING Axes: lines, scales, labels, spines,
+    legend, grid, and the per-figure override sweep (:func:`_apply_overrides`).
+    Returns the per-series drawn artist (a ``Line2D`` normally, or a
+    ``PathCollection`` for a colour-mapped-scatter series -- MAIN #14), in
+    ``series`` order, for the figure-hitmap element collector
+    (:func:`quantized.calc.figure_hitmap.collect_map`).
+
+    The single per-axes rendering body, shared by the single-figure renderer
+    (``_render_impl``) and the multi-panel page composer
+    (``figure_page.render_figure_page``) so a panel on a page looks exactly
+    like its single-figure export. Callers own the figure lifecycle (rc
+    context, layout, savefig, close) and must have sanitized every
+    user-supplied string through ``safe_mathtext_label`` already.
+
+    ``x_scale``/``y_scale`` (MAIN #12: "linear"/"log"/"reciprocal") are the
+    axis-scale source of truth when given; ``x_log``/``y_log`` are the
+    back-compat fallback for a caller that only sets the boolean (see
+    :func:`quantized.calc.figure_scale.resolve_axis_scale`).
+
+    Per-series ``series_styles`` (MAIN #13/#14, resolved against the raw
+    ``DataStruct`` by ``calc.plotting.resolve_style_channels`` -- this
+    function only ever sees resolved values): ``fill: "under"`` or
+    ``{"vs": <display index>}`` draws a translucent fill derived from the
+    series' own colour (:func:`_apply_fill`); ``color_by: <array>`` replaces
+    the normal line draw with a colour-mapped scatter + colourbar
+    (:func:`_draw_color_scatter`) instead.
+
+    ``x_fmt``/``y_fmt`` (MAIN #24: ``{"mode": "auto"|"fixed"|"sci"|"eng",
+    "digits": n}``) are the tick-label number format, mirroring the screen's
+    ``AxisFormat`` (see :func:`quantized.calc.figure_ticks.apply_tick_formats`);
+    ``None``/``"auto"`` leaves matplotlib's own default formatter untouched.
+    """
+    artists: list[Any] = []
+    for i, (label, y) in enumerate(series):
+        spec = series_styles[i] if series_styles and i < len(series_styles) else None
+        yv = np.asarray(y, dtype=float)
+        if spec and spec.get("color_by") is not None:
+            artists.append(_draw_color_scatter(fig, ax, xv, yv, label, spec, st))
+            continue
+        kw = _plot_kwargs(st.line_width, st.marker_size, spec)
+        (line,) = ax.plot(xv, yv, label=label, **kw)
+        _apply_fill(ax, xv, yv, series, i, spec, line.get_color())
+        artists.append(line)
+    apply_axis_scale(ax, "x", resolve_axis_scale(x_scale, x_log))
+    apply_axis_scale(ax, "y", resolve_axis_scale(y_scale, y_log))
+    apply_tick_formats(ax, x_fmt, y_fmt)
+    if title:
+        ax.set_title(title)
+    if x_label:
+        ax.set_xlabel(x_label)
+    if y_label:
+        ax.set_ylabel(y_label)
+    if not st.box_on:
+        ax.spines["top"].set_visible(False)
+        ax.spines["right"].set_visible(False)
+    if len(series) > 1 and "legend" not in ov:
+        # legend_location is a plain str (FigureStyle field); every preset's
+        # value is one of matplotlib's accepted location strings.
+        ax.legend(
+            frameon=st.legend_box,
+            fontsize=st.legend_font_size,
+            loc=st.legend_location,
+        )
+    if st.grid_alpha > 0:
+        ax.grid(True, alpha=st.grid_alpha)
+    else:
+        ax.grid(False)
+    _apply_overrides(fig, ax, st, ov, n_series=len(series))
+    return artists
+
+
+def _render_impl(
+    x: ArrayLike,
+    series: Sequence[tuple[str, ArrayLike]],
+    *,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    x_log: bool = False,
+    y_log: bool = False,
+    x_scale: str | None = None,
+    y_scale: str | None = None,
+    fmt: str = "pdf",
+    style: str = "default",
+    series_styles: Sequence[Mapping[str, Any] | None] | None = None,
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int | None = None,
+    overrides: Mapping[str, Any] | None = None,
+    collect_map: bool = False,
+    x_fmt: Mapping[str, Any] | None = None,
+    y_fmt: Mapping[str, Any] | None = None,
+) -> bytes | dict[str, Any]:
+    """Render ``series`` (each ``(label, y)``) against ``x`` to image bytes.
+
+    ``fmt`` is ``pdf`` / ``svg`` (vector) or ``png`` / ``tiff`` (raster, sized by
+    ``dpi``). ``style`` names a publication preset (``aps`` / ``report`` / ``web``
+    / …) that sets font, line width, figure geometry, grid, and legend; pass
+    ``width_in`` / ``height_in`` to override the preset's size. ``dpi`` defaults
+    to the preset's own calibrated resolution (e.g. ``aps`` / ``nature`` -> 600,
+    matching journal raster requirements) when not given explicitly; pass a
+    value to override it. ``title`` / ``x_label`` / ``y_label`` are optional
+    (empty = omit). ``series_styles`` (aligned 1:1 with ``series``) carries
+    per-series color/width/line/marker so the export matches the on-screen
+    plot, plus MAIN #13's ``fill`` (translucent fill under/between curves —
+    see :func:`_apply_fill`) and MAIN #14's ``color_by`` (colour-mapped
+    scatter + colourbar, replacing the line entirely for that series — see
+    :func:`_draw_color_scatter`); both expect values already resolved by
+    ``calc.plotting.resolve_style_channels`` (a raw channel index never
+    reaches this function). A legend is drawn only for multiple series, at
+    the preset's ``legend_location``. ``overrides`` (gap #11 — every property
+    UI-reachable) patches the preset per-figure: see :func:`_apply_overrides`;
+    unknown keys are ignored, invalid values raise ``ValueError``. Raises
+    ``ValueError`` on an unknown format or style. ``x_scale``/``y_scale``
+    (MAIN #12) select linear/log/reciprocal; ``x_log``/``y_log`` are the
+    back-compat boolean fallback (see :func:`draw_series_axes`'s doc).
+    ``x_fmt``/``y_fmt`` (MAIN #24) are the tick-label number format -- see
+    :func:`draw_series_axes`'s doc.
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    # Rich-text labels (GOTO #5): valid $...$ mathtext passes through to
+    # matplotlib untouched; INVALID mathtext is de-mathed here so it renders
+    # literally instead of raising inside savefig (an export must never 500).
+    # Sanitizing at entry also covers the figure_break branch below, which
+    # receives these same strings.
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+    series = [(safe_mathtext_label(label), y) for label, y in series]
+    st = figure_style(style)
+    ov = dict(overrides or {})
+    _validate_overrides(ov)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+
+    # rc_context scopes typography to this render (see style_rc). (matplotlib's
+    # RcParams Literal-key type is impractical with the dynamic font.<generic>
+    # key, hence the targeted ignore at the context below.)
+    rc = style_rc(st, ov)
+    figsize = (width_in or st.fig_width_in, height_in or st.fig_height_in)
+
+    xv: NDArray[np.float64] = np.asarray(x, dtype=float)
+    x_breaks = ov.get("x_breaks")
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        # Manual axis breaks (gap #21): a distinct, twinned-panel rendering
+        # path — not compatible with the hit-map collector (collect_map is
+        # figure-hitmap's single-axes pixel harvesting) or the full
+        # `_apply_overrides` sweep (legend/spines/limits/margins apply to a
+        # SINGLE axes; a broken figure has several). Breaks render the plot +
+        # title/labels/basic legend/grid honestly; other overrides are simply
+        # not applied together with x_breaks in this pass.
+        if x_breaks and not collect_map:
+            # Lazy import: split out purely to stay under the 500-line ceiling.
+            from quantized.calc.figure_break import render_breaks_impl
+
+            return render_breaks_impl(
+                xv,
+                series,
+                breaks=[(float(b[0]), float(b[1])) for b in x_breaks],
+                x_log=x_log,
+                y_log=y_log,
+                x_scale=x_scale,
+                y_scale=y_scale,
+                title=title,
+                x_label=x_label,
+                y_label=y_label,
+                fmt=fmt,
+                st=st,
+                ov=ov,
+                dpi=resolved_dpi,
+                figsize=figsize,
+                series_styles=series_styles,
+                x_fmt=x_fmt,
+                y_fmt=y_fmt,
+            )
+        fig, ax = plt.subplots(figsize=figsize)
+        try:
+            artists = draw_series_axes(
+                fig,
+                ax,
+                xv,
+                series,
+                st=st,
+                ov=ov,
+                x_log=x_log,
+                y_log=y_log,
+                x_scale=x_scale,
+                y_scale=y_scale,
+                title=title,
+                x_label=x_label,
+                y_label=y_label,
+                series_styles=series_styles,
+                x_fmt=x_fmt,
+                y_fmt=y_fmt,
+            )
+            if not ov.get("margins"):
+                fig.tight_layout()
+            if collect_map:
+                return _collect_map_impl(
+                    fig,
+                    ax,
+                    series_artists=artists,
+                    dpi=resolved_dpi,
+                    x_scale=resolve_axis_scale(x_scale, x_log),
+                    y_scale=resolve_axis_scale(y_scale, y_log),
+                )
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def render_figure(
+    x: ArrayLike,
+    series: Sequence[tuple[str, ArrayLike]],
+    **kwargs: Any,
+) -> bytes:
+    """Render ``series`` against ``x`` to image bytes (see ``_render_impl``)."""
+    out = _render_impl(x, series, **kwargs)
+    assert isinstance(out, bytes)
+    return out
+
+
+def render_figure_map(
+    x: ArrayLike,
+    series: Sequence[tuple[str, ArrayLike]],
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """Render a PNG AND its element hit-map (gap #13): base64 image + one
+    pixel bounding box per interactive artist (title / axis labels / legend /
+    series lines / annotations) + the axes rect with data limits, so the
+    client can hit-test the preview and map pixels back to data coords."""
+    kwargs.pop("fmt", None)
+    out = _render_impl(x, series, fmt="png", collect_map=True, **kwargs)
+    assert isinstance(out, dict)
+    return out