quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/figure_overrides.py

@@ -0,0 +1,159 @@
+"""Figure property overrides (gap #11). Split out of ``calc.figure`` purely to
+stay under the 500-line god-module ceiling (the same reason ``figure_break.py``
+and ``figure_labels.py`` exist separately) -- the behavioural contract is still
+``calc.figure``'s; ``_render_impl`` calls ``_validate_overrides`` up front and
+``draw_series_axes`` calls ``_apply_overrides`` as its last step. Pure layer:
+mapping in -> mutates the passed matplotlib Figure/Axes, no return value.
+
+The one config object behind the property panels: every export property the
+UI exposes lands in ``overrides``, patching the preset per-figure. Plain dict
+(calc stays pydantic-free); unknown keys are ignored so old clients keep
+working.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from quantized.calc.figure_labels import safe_mathtext_label
+
+__all__ = ["_apply_overrides", "_validate_overrides"]
+
+_LEGEND_LOCS = frozenset({
+    "best", "upper right", "upper left", "lower left", "lower right",
+    "right", "center left", "center right", "lower center", "upper center",
+    "center", "outside right", "outside top", "custom",
+})
+
+
+def _validate_overrides(ov: Mapping[str, Any]) -> None:
+    """Raise ``ValueError`` on invalid override values (bad keys are ignored)."""
+    legend = ov.get("legend")
+    if legend is not None:
+        loc = legend.get("loc")
+        if loc is not None and loc not in _LEGEND_LOCS:
+            raise ValueError(f"legend loc must be one of {sorted(_LEGEND_LOCS)}")
+    ticks = ov.get("ticks")
+    if ticks is not None:
+        tdir = ticks.get("dir")
+        if tdir is not None and tdir not in ("in", "out"):
+            raise ValueError("ticks dir must be 'in' or 'out'")
+    for key in ("x_lim", "y_lim"):
+        lim = ov.get(key)
+        if lim is not None and (not isinstance(lim, (list, tuple)) or len(lim) != 2):
+            raise ValueError(f"{key} must be a [lo, hi] pair (null member = auto)")
+    margins = ov.get("margins")
+    if margins is not None:
+        for side in ("left", "right", "top", "bottom"):
+            v = margins.get(side)
+            if v is not None and not 0.0 <= float(v) <= 1.0:
+                raise ValueError("margins are figure fractions in [0, 1]")
+    breaks = ov.get("x_breaks")
+    if breaks is not None:
+        if not isinstance(breaks, (list, tuple)) or len(breaks) == 0:
+            raise ValueError("x_breaks must be a non-empty list of [lo, hi] pairs")
+        prev_hi: float | None = None
+        for b in breaks:
+            if not isinstance(b, (list, tuple)) or len(b) != 2:
+                raise ValueError("each x_breaks entry must be a [lo, hi] pair")
+            lo, hi = float(b[0]), float(b[1])
+            if not lo < hi:
+                raise ValueError("each x_breaks entry must have lo < hi")
+            if prev_hi is not None and lo < prev_hi:
+                raise ValueError("x_breaks entries must be sorted and non-overlapping")
+            prev_hi = hi
+
+
+def _apply_overrides(
+    fig: Any, ax: Any, st: Any, ov: Mapping[str, Any], *, n_series: int
+) -> None:
+    """Apply the post-plot override properties (legend / ticks / spines /
+    limits / margins / grid / annotations). rc-level properties (fonts, tick
+    direction/length) are folded into the rc context by the caller."""
+    legend = ov.get("legend")
+    if legend is not None:
+        show = legend.get("show")
+        if (show is None and n_series > 1) or show:
+            frame = bool(legend.get("frame", st.legend_box))
+            loc = str(legend.get("loc", "best"))
+            kw: dict[str, Any] = {"frameon": frame, "fontsize": st.legend_font_size}
+            if loc == "outside right":
+                kw.update(loc="center left", bbox_to_anchor=(1.02, 0.5))
+            elif loc == "outside top":
+                kw.update(loc="lower center", bbox_to_anchor=(0.5, 1.02), ncols=max(1, n_series))
+            elif loc == "custom":
+                # #14 drag-to-place: anchor is a figure-fraction (fx, fy).
+                anchor = legend.get("anchor") or (0.5, 0.5)
+                kw.update(
+                    loc="center",
+                    bbox_to_anchor=(float(anchor[0]), float(anchor[1])),
+                    bbox_transform=fig.transFigure,
+                )
+            else:
+                kw["loc"] = loc
+            ax.legend(**kw)
+        elif ax.get_legend() is not None:
+            ax.get_legend().remove()
+
+    ticks = ov.get("ticks")
+    if ticks is not None and ticks.get("minor"):
+        ax.minorticks_on()
+
+    spines = ov.get("spines")
+    if spines is not None:
+        for side in ("top", "right", "left", "bottom"):
+            if side in spines:
+                ax.spines[side].set_visible(bool(spines[side]))
+
+    for key, setter in (("x_lim", ax.set_xlim), ("y_lim", ax.set_ylim)):
+        lim = ov.get(key)
+        if lim is not None:
+            lo, hi = lim
+            setter(
+                None if lo is None else float(lo),
+                None if hi is None else float(hi),
+            )
+
+    if "grid" in ov:
+        ax.grid(bool(ov["grid"]), alpha=st.grid_alpha or 0.3)
+
+    for ann in ov.get("annotations", []):
+        # MAIN #18: a per-annotation `size` (the pointer tool's corner-handle
+        # font-size resize, screen px) wins over the property panel's global
+        # font_size override -- matches the screen, where each annotation's
+        # OWN size (Annotation.size) always overrides the plot's base font.
+        size = ann.get("size")
+        ann_kw: dict[str, Any] = {}
+        x, y = float(ann.get("x", 0.0)), float(ann.get("y", 0.0))
+        if ann.get("anchor") == "page":
+            # MAIN #21: page-anchored on screen (CANVAS fractions, x
+            # rightward/y DOWNWARD -- see Annotation.anchor's doc) -> figure
+            # fraction placement (x rightward/y UPWARD) rather than
+            # axes-data coords, so the label stays pinned to the same page
+            # position independent of the axes' data range. The Y AXIS IS
+            # FLIPPED between the two conventions -- canvas y=0 is the top,
+            # figure fraction y=0 is the bottom -- so `1 - y` is required,
+            # not optional. Canvas fractions and matplotlib figure fractions
+            # are NOT geometrically identical (the canvas includes the axes
+            # margins at a different proportion than matplotlib's own
+            # figure margins) -- this is deliberately Origin-parity-in-
+            # spirit (pin to the page, stay put through zoom/pan), not
+            # pixel-identical placement between screen and export.
+            ann_kw["xycoords"] = "figure fraction"
+            y = 1.0 - y
+        ax.annotate(
+            safe_mathtext_label(str(ann.get("text", ""))),
+            xy=(x, y),
+            fontsize=float(size) if size else float(ov.get("font_size", st.font_size)),
+            **ann_kw,
+        )
+
+    margins = ov.get("margins")
+    if margins is not None:
+        fig.subplots_adjust(
+            left=margins.get("left"),
+            right=None if margins.get("right") is None else 1.0 - float(margins["right"]),
+            top=None if margins.get("top") is None else 1.0 - float(margins["top"]),
+            bottom=margins.get("bottom"),
+        )

quantized/calc/figure_page.py

@@ -0,0 +1,266 @@
+"""Multi-panel figure page composition (GOTO #4): N different plots -> ONE page.
+
+Pure layer: panel data in -> image bytes out. Composes pre-built panels (each
+the same ``(x, series)`` payload ``calc.figure`` renders singly) onto a single
+matplotlib page: a rows x cols grid with optional per-panel row/col spans,
+journal-style panel labels ("(a)", "(b)", ... -- auto-generated in row-major
+placement order, or overridden per panel), and ONE style preset applied
+page-wide. This is the "Figure 1(a)-(d)" workflow with zero external
+post-processing: PDF / SVG vector by default, PNG / TIFF raster at a chosen
+DPI (the low-DPI PNG render doubles as the composer UI's preview image).
+
+The per-axes rendering body is shared with the single-figure renderer via
+``figure.draw_series_axes``, so a panel on a page looks exactly like its
+single-figure export. Every user-supplied string (panel titles, axis labels,
+series labels, panel labels) is routed through the GOTO #5 rich-text guard
+(``figure_labels.safe_mathtext_label``): valid ``$...$`` mathtext renders,
+invalid markup degrades to literal text -- an export must never error on a
+label. Two single-figure overrides are page-incompatible and rejected with a
+clear ``ValueError`` (-> 422 at the route): per-panel ``x_breaks`` (the break
+renderer owns its own figure) and per-panel ``margins`` (page layout is
+constrained-layout, figure-level).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+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  # noqa: E402
+from numpy.typing import ArrayLike  # noqa: E402
+
+from quantized.calc.figure import draw_series_axes, style_rc  # noqa: E402
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_overrides import _validate_overrides  # noqa: E402
+from quantized.calc.figure_styles import FigureStyle, figure_style  # noqa: E402
+
+__all__ = ["PagePanel", "panel_label", "render_figure_page"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+_LABEL_POSITIONS = ("nw", "ne", "outside")
+# Auto-label formats, keyed by the rendered form of the FIRST panel:
+# (wrap template, uppercase letters?). "none" suppresses auto labels entirely.
+_LABEL_TEMPLATES: dict[str, tuple[str, bool]] = {
+    "(a)": ("({})", False),
+    "a)": ("{})", False),
+    "a.": ("{}.", False),
+    "(A)": ("({})", True),
+    "A)": ("{})", True),
+    "A.": ("{}.", True),
+}
+# Grid cap: a journal page never needs more; guards absurd allocations.
+_MAX_GRID = 8
+
+
+def _letters(index: int) -> str:
+    """0 -> "a", 25 -> "z", 26 -> "aa", ... (spreadsheet-style rollover)."""
+    out = ""
+    n = index
+    while True:
+        out = chr(ord("a") + n % 26) + out
+        n = n // 26 - 1
+        if n < 0:
+            return out
+
+
+def panel_label(index: int, label_format: str = "(a)") -> str:
+    """The auto-generated label for the ``index``-th panel (0-based, row-major
+    placement order): ``panel_label(1, "(a)") == "(b)"``. ``"none"`` returns
+    an empty string (no labels). Raises ``ValueError`` on an unknown format
+    or a negative index."""
+    if index < 0:
+        raise ValueError("panel index must be >= 0")
+    if label_format == "none":
+        return ""
+    try:
+        template, upper = _LABEL_TEMPLATES[label_format]
+    except KeyError as exc:
+        allowed = (*_LABEL_TEMPLATES, "none")
+        raise ValueError(f"label_format must be one of {allowed}") from exc
+    letters = _letters(index)
+    return template.format(letters.upper() if upper else letters)
+
+
+@dataclass(frozen=True)
+class PagePanel:
+    """One panel of a figure page: the same ``(x, series)`` payload
+    ``calc.figure`` renders singly, plus its grid placement. ``label=None``
+    means auto ("(a)", "(b)", ... in row-major placement order); ``label=""``
+    suppresses the label on this panel only."""
+
+    x: ArrayLike
+    series: Sequence[tuple[str, ArrayLike]]
+    row: int
+    col: int
+    row_span: int = 1
+    col_span: int = 1
+    title: str = ""
+    x_label: str = ""
+    y_label: str = ""
+    x_log: bool = False
+    y_log: bool = False
+    # MAIN #12: linear/log/reciprocal, source of truth when set; x_log/y_log
+    # are the back-compat fallback (see figure_scale.resolve_axis_scale).
+    x_scale: str | None = None
+    y_scale: str | None = None
+    # MAIN #24: tick-label number format ({"mode": ..., "digits": ...},
+    # AxisFormat-shaped) -- each panel carries its OWN, mirroring the screen
+    # (a figure page composes several independently-configured plot views).
+    x_fmt: Mapping[str, Any] | None = None
+    y_fmt: Mapping[str, Any] | None = None
+    series_styles: Sequence[Mapping[str, Any] | None] | None = None
+    overrides: Mapping[str, Any] | None = None
+    label: str | None = None
+
+
+def _validate_page(rows: int, cols: int, panels: Sequence[PagePanel]) -> None:
+    """Raise ``ValueError`` on an invalid page spec: bad grid, empty page,
+    out-of-bounds or overlapping panels, page-incompatible overrides."""
+    if rows < 1 or cols < 1:
+        raise ValueError("page grid must have at least 1 row and 1 column")
+    if rows > _MAX_GRID or cols > _MAX_GRID:
+        raise ValueError(f"page grid is capped at {_MAX_GRID}x{_MAX_GRID}")
+    if not panels:
+        raise ValueError("page must contain at least one panel")
+    occupied: dict[tuple[int, int], int] = {}
+    for n, p in enumerate(panels):
+        if p.row_span < 1 or p.col_span < 1:
+            raise ValueError(f"panel {n}: row_span and col_span must be >= 1")
+        if p.row < 0 or p.col < 0 or p.row + p.row_span > rows or p.col + p.col_span > cols:
+            raise ValueError(
+                f"panel {n} does not fit the {rows}x{cols} grid (row={p.row} "
+                f"col={p.col} row_span={p.row_span} col_span={p.col_span})"
+            )
+        for r in range(p.row, p.row + p.row_span):
+            for c in range(p.col, p.col + p.col_span):
+                other = occupied.get((r, c))
+                if other is not None:
+                    raise ValueError(f"panels {other} and {n} overlap at grid cell ({r}, {c})")
+                occupied[(r, c)] = n
+        ov = dict(p.overrides or {})
+        if "x_breaks" in ov:
+            raise ValueError(f"panel {n}: x_breaks is not supported on a figure page")
+        if "margins" in ov:
+            raise ValueError(
+                f"panel {n}: margins are page-level on a figure page; "
+                "remove the per-panel margins override"
+            )
+        _validate_overrides(ov)
+
+
+def _place_label(ax: Any, text: str, pos: str, st: FigureStyle) -> None:
+    """Draw one panel label. ``nw``/``ne`` sit inside the axes at the top
+    corner; ``outside`` uses matplotlib's LEFT title slot above the axes,
+    which coexists with the panel's own (center) title -- the standard
+    journal placement."""
+    if not text:
+        return
+    size = float(st.title_font_size)
+    if pos == "outside":
+        ax.set_title(text, loc="left", fontweight="bold", fontsize=size)
+    elif pos == "ne":
+        ax.text(
+            0.97, 0.96, text, transform=ax.transAxes,
+            ha="right", va="top", fontweight="bold", fontsize=size,
+        )
+    else:  # "nw"
+        ax.text(
+            0.03, 0.96, text, transform=ax.transAxes,
+            ha="left", va="top", fontweight="bold", fontsize=size,
+        )
+
+
+def render_figure_page(
+    panels: Sequence[PagePanel],
+    *,
+    rows: int,
+    cols: int,
+    fmt: str = "pdf",
+    style: str = "default",
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int | None = None,
+    label_format: str = "(a)",
+    label_pos: str = "nw",
+) -> bytes:
+    """Compose ``panels`` onto one rows x cols page and render to image bytes.
+
+    ``fmt`` is ``pdf`` / ``svg`` (vector, the default convention) or ``png`` /
+    ``tiff`` (raster at ``dpi``; ``None`` = the preset's calibrated dpi).
+    ``style`` names a publication preset applied page-wide (fonts, line
+    widths, box/ticks/grid). Page size: ``width_in`` defaults to the preset's
+    figure width -- the journal-column convention the preset encodes (``aps``
+    8.6 cm ~ 3.39 in single column; ``aps_double`` 17.8 cm ~ 7.0 in double
+    column, the APS sizes) -- and ``height_in`` defaults so each grid cell
+    keeps the preset's own aspect ratio. ``label_format`` / ``label_pos``
+    control the auto panel labels (see :func:`panel_label`, :func:`_place_label`);
+    a panel's explicit ``label`` wins over the auto sequence. Raises
+    ``ValueError`` on any invalid spec (unknown format/style/label options,
+    empty grid, out-of-bounds or overlapping panels).
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if label_pos not in _LABEL_POSITIONS:
+        raise ValueError(f"label_pos must be one of {_LABEL_POSITIONS}")
+    if label_format != "none" and label_format not in _LABEL_TEMPLATES:
+        allowed = (*_LABEL_TEMPLATES, "none")
+        raise ValueError(f"label_format must be one of {allowed}")
+    _validate_page(rows, cols, panels)
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+
+    w = float(width_in) if width_in is not None else st.fig_width_in
+    h = (
+        float(height_in)
+        if height_in is not None
+        else w * (st.fig_height_in / st.fig_width_in) * (rows / cols)
+    )
+    if w <= 0 or h <= 0:
+        raise ValueError("width_in and height_in must be positive")
+
+    # Row-major placement order defines the auto-label sequence.
+    ordered = sorted(panels, key=lambda p: (p.row, p.col))
+    # (matplotlib's RcParams Literal-key type is impractical with the dynamic
+    # font.<generic> key -- same targeted ignore as calc.figure.)
+    with matplotlib.rc_context(style_rc(st, {})):  # type: ignore[arg-type]
+        fig = plt.figure(figsize=(w, h), layout="constrained")
+        try:
+            gs = fig.add_gridspec(rows, cols)
+            for idx, p in enumerate(ordered):
+                ax = fig.add_subplot(
+                    gs[p.row : p.row + p.row_span, p.col : p.col + p.col_span]
+                )
+                # Rich-text guard (GOTO #5) on every user string; see figure.py.
+                series = [(safe_mathtext_label(label), y) for label, y in p.series]
+                draw_series_axes(
+                    fig,
+                    ax,
+                    np.asarray(p.x, dtype=float),
+                    series,
+                    st=st,
+                    ov=dict(p.overrides or {}),
+                    x_log=p.x_log,
+                    y_log=p.y_log,
+                    x_scale=p.x_scale,
+                    y_scale=p.y_scale,
+                    title=safe_mathtext_label(p.title),
+                    x_label=safe_mathtext_label(p.x_label),
+                    y_label=safe_mathtext_label(p.y_label),
+                    series_styles=p.series_styles,
+                    x_fmt=p.x_fmt,
+                    y_fmt=p.y_fmt,
+                )
+                text = p.label if p.label is not None else panel_label(idx, label_format)
+                _place_label(ax, safe_mathtext_label(text), label_pos, st)
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)

quantized/calc/figure_scale.py

@@ -0,0 +1,125 @@
+"""Axis-scale resolution + the reciprocal (1/x) transform for matplotlib
+export (MAIN #12 -- Arrhenius-style plots: ln(rho) or log tau vs 1/T). Pure
+layer. Split out of ``calc.figure`` purely to stay under the 500-line
+god-module ceiling (mirrors ``figure_break``/``figure_overrides``).
+
+matplotlib has no built-in reciprocal scale, so this applies one via
+``Axes.set_xscale("function", functions=(f, finv))`` -- matplotlib's own
+documented custom-scale hook (``matplotlib.scale.FuncScale``) -- with the
+self-inverse transform ``f(v) = 1/v`` (``f(f(v)) == v`` for ``v != 0``, so one
+function serves as both the forward and inverse transform) plus a tick
+locator that places ticks at "nice" values evenly spaced IN 1/x SPACE,
+returned in the ORIGINAL x units. That mirrors the screen-side reciprocal
+scale (``frontend/src/lib/uplotOpts.ts``'s ``reciprocalTransform`` /
+``reciprocalAxisSplits``): the axis POSITIONS by 1/x, but tick LABELS still
+read the natural variable (e.g. T in Kelvin) -- Origin's "Reciprocal" axis
+type convention.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from matplotlib.ticker import Locator
+from numpy.typing import NDArray
+
+__all__ = ["apply_axis_scale", "reciprocal_tick_values", "resolve_axis_scale"]
+
+_SCALES = ("linear", "log", "reciprocal")
+
+
+def resolve_axis_scale(explicit: str | None, legacy_log: bool) -> str:
+    """MAIN #12 back-compat bridge: an explicit ``x_scale``/``y_scale`` (a
+    new caller) wins when it's one of the 3 valid tokens; otherwise fall back
+    to the old ``x_log``/``y_log`` boolean (``True`` -> ``"log"``, ``False``
+    -> ``"linear"``) -- the same convention as the frontend's
+    ``lib/plotview.ts``'s ``scaleFromLog``."""
+    if explicit in _SCALES:
+        return explicit
+    return "log" if legacy_log else "linear"
+
+
+def _reciprocal(v: NDArray[np.float64] | float) -> NDArray[np.float64]:
+    """``1/v``, self-inverse. Non-positive input degrades to ``NaN`` --
+    matplotlib omits a NaN point from the drawn view rather than erroring --
+    the SAME domain restriction the log scale already has (physically apt
+    for the Arrhenius case: T in Kelvin is always positive)."""
+    arr = np.asarray(v, dtype=float)
+    out = np.full_like(arr, np.nan)
+    pos = arr > 0
+    out[pos] = 1.0 / arr[pos]
+    return out
+
+
+def _nice_step(raw: float) -> float:
+    """A nice round step >= raw, snapped to 1/2/5/10 x 10^n (mirrors the
+    frontend's ``niceLinearStep``)."""
+    if raw <= 0 or not np.isfinite(raw):
+        return 1.0
+    mag = float(10.0 ** np.floor(np.log10(raw)))
+    norm = raw / mag
+    snapped = 1.0 if norm < 1.5 else 2.0 if norm < 3.0 else 5.0 if norm < 7.0 else 10.0
+    return snapped * mag
+
+
+def reciprocal_tick_values(vmin: float, vmax: float, target: int = 5) -> list[float]:
+    """Reciprocal-axis tick positions for a ``[vmin, vmax]`` data-space range:
+    "nice" values evenly spaced in 1/x space, mapped back to ORIGINAL x units
+    (mirrors the frontend's ``reciprocalAxisSplits``). Degenerate ranges
+    (non-positive, or inverted/zero-width) return ``[]``."""
+    if not (vmin > 0) or not (vmax > vmin):
+        return []
+    r0, r1 = 1.0 / vmin, 1.0 / vmax
+    lo, hi = min(r0, r1), max(r0, r1)
+    if not (hi > lo):
+        return [vmin, vmax]
+    step = _nice_step((hi - lo) / max(1, target))
+    eps = 1e-9
+    n0 = int(np.ceil(lo / step - eps))
+    n1 = int(np.floor(hi / step + eps))
+    out: list[float] = []
+    for n in range(n0, n1 + 1):
+        r = n * step
+        if r == 0:
+            continue  # 1/0 is undefined -- skip the (rare) exact-zero tick
+        v = float(np.round(1.0 / r, 10))
+        if vmin * (1 - eps) <= v <= vmax * (1 + eps):
+            out.append(v)
+    return sorted(out)
+
+
+class _ReciprocalLocator(Locator):
+    """Matplotlib tick locator for a reciprocal-scaled axis: ticks land at
+    "nice" 1/x-evenly-spaced values, returned in ORIGINAL x units (see
+    :func:`reciprocal_tick_values`). ``self.axis`` is set by matplotlib when
+    the locator is attached via ``set_major_locator``."""
+
+    def tick_values(self, vmin: float, vmax: float) -> list[float]:
+        return reciprocal_tick_values(min(vmin, vmax), max(vmin, vmax))
+
+    def __call__(self) -> list[float]:
+        if self.axis is None:
+            return []
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+
+def apply_axis_scale(ax: Any, axis: str, scale: str) -> None:
+    """Apply ``scale`` (``"linear"``/``"log"``/``"reciprocal"``) to ``ax``'s
+    x or y axis (``axis`` is ``"x"`` or ``"y"``). ``"linear"`` is a no-op
+    (matplotlib's own default). ``"reciprocal"`` uses the ``"function"``
+    scale (matplotlib's documented custom-scale hook,
+    :class:`matplotlib.scale.FuncScale`) with the self-inverse 1/x transform
+    plus :class:`_ReciprocalLocator` for reciprocal-spaced ticks."""
+    set_scale = ax.set_xscale if axis == "x" else ax.set_yscale
+    if scale == "log":
+        set_scale("log")
+        return
+    if scale == "reciprocal":
+        set_scale("function", functions=(_reciprocal, _reciprocal))
+        locator = _ReciprocalLocator()
+        if axis == "x":
+            ax.xaxis.set_major_locator(locator)
+        else:
+            ax.yaxis.set_major_locator(locator)