paperplot-quantum 0.1.0__py3-none-any.whl

paperplot/plots.py

@@ -0,0 +1,310 @@
+"""Opinionated publication plot helpers — the few composites that come up over and
+over in physics figures and that bare matplotlib makes fiddly:
+
+* :func:`hist_outline` — a translucent filled histogram with a crisp staircase
+  outline drawn on top. The outline is what keeps *overlapping* histograms
+  legible; ``ax.hist`` alone muddies them.
+* :func:`hist_filled` — the lighter, centers-based shaded histogram
+  (``fill_between(step="mid")`` + ``steps-mid`` line), with optional peak rescale.
+* :func:`data_fit_band` — the "data points (error bars, black-edged markers) +
+  bold fit line + shaded confidence band" composite used for ZNE / decay fits.
+* :func:`swatches` — render color swatches to eyeball a palette (the inline
+  ``display(sns.color_palette(...))`` experience, but in matplotlib).
+
+matplotlib-only by default; :func:`hist_outline` has an opt-in ``use_seaborn``
+path that draws the fill via ``seaborn.histplot`` (KDE, multiple stats, etc.).
+The default colors follow paperplot's fill/stroke convention: muted fills under
+bright/black strokes (see :func:`paperplot.fills` / :func:`paperplot.strokes`).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+from . import palettes
+
+
+def _ensure_ax(ax):
+    if ax is None:
+        import matplotlib.pyplot as plt
+        _, ax = plt.subplots()
+    return ax
+
+
+def _staircase(counts, edges):
+    """Bin counts/edges -> (x, y) tracing the histogram outline as a staircase."""
+    x = np.repeat(edges, 2)[1:-1]
+    y = np.repeat(counts, 2)
+    return x, y
+
+
+def hist_outline(
+    data,
+    ax=None,
+    *,
+    bins=50,
+    range=None,
+    density=False,
+    rescale=False,
+    color=None,
+    alpha=0.6,
+    fill=True,
+    label=None,
+    outline_color="k",
+    outline_lw=1.0,
+    outline_kw: Optional[dict] = None,
+    zorder=None,
+    use_seaborn=False,
+    **fill_kw,
+):
+    """Filled histogram with a solid staircase outline traced over the bars.
+
+    Returns ``(ax, (counts, edges))``. The fill carries the legend ``label``.
+
+    Parameters
+    ----------
+    data : array-like
+        Samples to histogram.
+    bins, range, density :
+        Passed to ``numpy.histogram`` (and to ``seaborn.histplot`` when
+        ``use_seaborn=True``). ``density`` controls the y-scale.
+    rescale : bool
+        Normalize counts so the tallest bin is 1 (a "relative probability"
+        y-axis). Ignored when ``density=True``.
+    color : color, optional
+        Fill color. Defaults to the first muted fill color (``pp.fills()[0]``).
+    outline_color, outline_lw, outline_kw :
+        The staircase outline. ``outline_kw`` overrides any of these per call.
+    use_seaborn : bool
+        Draw the fill via ``seaborn.histplot`` (enables KDE, stat=, etc. through
+        ``**fill_kw``) instead of ``ax.fill_between``. The outline is always
+        matplotlib. Raises ``ImportError`` if seaborn is not installed.
+    """
+    ax = _ensure_ax(ax)
+    if color is None:
+        color = palettes.fills()[0]
+    z = {} if zorder is None else {"zorder": zorder}
+
+    counts, edges = np.histogram(data, bins=bins, range=range, density=density)
+    counts = counts.astype(float)
+    if rescale and not density and counts.max() > 0:
+        counts = counts / counts.max()
+
+    if use_seaborn:
+        import seaborn as sns  # optional extra; only imported on request
+        sns.histplot(
+            data, ax=ax, bins=bins, binrange=range,
+            stat="density" if density else "count",
+            color=color, alpha=alpha, label=label, **z, **fill_kw,
+        )
+    elif fill:
+        x, y = _staircase(counts, edges)
+        ax.fill_between(x, y, color=color, alpha=alpha, linewidth=0,
+                        label=label, **z, **fill_kw)
+
+    x, y = _staircase(counts, edges)
+    okw = {"color": outline_color, "linestyle": "-", "linewidth": outline_lw}
+    okw.update(z)
+    if outline_kw:
+        okw.update(outline_kw)
+    # If there is no fill to carry the label (fill=False, no seaborn), let the
+    # outline carry it instead.
+    if label is not None and not fill and not use_seaborn:
+        okw.setdefault("label", label)
+    ax.plot(x, y, **okw)
+
+    return ax, (counts, edges)
+
+
+def hist_filled(
+    data,
+    ax=None,
+    *,
+    bins=50,
+    range=None,
+    density=False,
+    rescale=False,
+    color=None,
+    alpha=0.7,
+    label=None,
+    line_color="k",
+    line_lw=1.0,
+    line_kw: Optional[dict] = None,
+    fill_kw: Optional[dict] = None,
+    zorder=None,
+):
+    """Shaded histogram drawn on bin *centers* (``steps-mid``), with a line on top.
+
+    Lighter sibling of :func:`hist_outline` — the shape is centered on bins rather
+    than tracing the bar edges. Returns ``(counts, edges, centers)``.
+    """
+    ax = _ensure_ax(ax)
+    if color is None:
+        color = palettes.fills()[0]
+    z = {} if zorder is None else {"zorder": zorder}
+
+    counts, edges = np.histogram(data, bins=bins, range=range, density=density)
+    counts = counts.astype(float)
+    if rescale and not density and counts.max() > 0:
+        counts = counts / counts.max()
+    centers = (edges[:-1] + edges[1:]) / 2
+
+    fkw = {"step": "mid", "alpha": alpha, "color": color, "linewidth": 0,
+           "label": label}
+    fkw.update(z)
+    if fill_kw:
+        fkw.update(fill_kw)
+    ax.fill_between(centers, counts, **fkw)
+
+    lkw = {"drawstyle": "steps-mid", "color": line_color, "linewidth": line_lw}
+    lkw.update(z)
+    if line_kw:
+        lkw.update(line_kw)
+    ax.plot(centers, counts, **lkw)
+
+    return counts, edges, centers
+
+
+def data_fit_band(
+    ax,
+    x,
+    y,
+    *,
+    yerr=None,
+    x_fit=None,
+    y_fit=None,
+    y_fit_err=None,
+    color=None,
+    fit_color=None,
+    band_color=None,
+    label=None,
+    fit_label=None,
+    band_alpha=0.2,
+    data_kw: Optional[dict] = None,
+    fit_kw: Optional[dict] = None,
+    band_kw: Optional[dict] = None,
+):
+    """Plot measured data with error bars, an overlaid fit line, and a CI band.
+
+    The standard decay-fit composite:
+
+    * data as black-edged markers with error bars (``capsize``, thin ``mew``),
+    * a bold fit line drawn *behind* the markers (``zorder=0``),
+    * a translucent confidence band from ``y_fit ± y_fit_err`` (``zorder=-1``).
+
+    Pass ``x_fit``/``y_fit`` (e.g. from ``lmfit`` ``result.eval``) to draw the
+    fit, and ``y_fit_err`` (e.g. ``result.eval_uncertainty``) to add the band.
+    ``color`` is the data color; ``fit_color`` and ``band_color`` default to it.
+    """
+    if color is None:
+        color = palettes.strokes()[0]
+    if fit_color is None:
+        fit_color = color
+    if band_color is None:
+        band_color = fit_color
+
+    dkw = {"fmt": "o", "ms": 3, "mec": "k", "mew": 0.25, "lw": 0.5,
+           "capsize": 3, "color": color, "label": label}
+    if data_kw:
+        dkw.update(data_kw)
+    ax.errorbar(x, y, yerr=yerr, **dkw)
+
+    if x_fit is not None and y_fit is not None:
+        fkw = {"lw": 2.0, "zorder": 0, "color": fit_color, "label": fit_label}
+        if fit_kw:
+            fkw.update(fit_kw)
+        ax.plot(x_fit, y_fit, **fkw)
+
+        if y_fit_err is not None:
+            bkw = {"alpha": band_alpha, "color": band_color, "zorder": -1,
+                   "linewidth": 0}
+            if band_kw:
+                bkw.update(band_kw)
+            y_fit = np.asarray(y_fit)
+            y_fit_err = np.asarray(y_fit_err)
+            ax.fill_between(x_fit, y_fit - y_fit_err, y_fit + y_fit_err, **bkw)
+
+    return ax
+
+
+def _draw_swatch_rows(ax, rows, *, tags=None, tag_color="#1a7f4b"):
+    """Draw labeled swatch rows on ``ax``. ``rows`` is a list of (name, colors);
+    ``tags`` is an optional list of short right-side annotations (one per row)."""
+    import matplotlib.pyplot as plt
+
+    nrows = len(rows)
+    ncols = max((len(c) for _, c in rows), default=0)
+    for r, (name, cols) in enumerate(rows):
+        yr = nrows - 1 - r
+        for i, c in enumerate(cols):
+            ax.add_patch(plt.Rectangle((i, yr + 0.04), 0.92, 0.92, color=c))
+        if name:
+            ax.text(-0.25, yr + 0.5, str(name), ha="right", va="center")
+        if tags and tags[r]:
+            ax.text(ncols + 0.25, yr + 0.5, tags[r], ha="left", va="center",
+                    color=tag_color, weight="bold")
+    ax.set_xlim(0, ncols)
+    ax.set_ylim(0, nrows)
+    ax.axis("off")
+    return ncols, nrows
+
+
+def swatches(colors, ax=None, *, labels=None, size=0.6):
+    """Render color swatches — eyeball a palette or compare fills vs strokes.
+
+    ``colors`` is a list of colors (one row) or a ``{name: [colors]}`` dict (one
+    row per name). Returns the ``Figure``. The matplotlib analogue of
+    ``display(sns.color_palette(...))`` in a notebook.
+    """
+    import matplotlib.pyplot as plt
+
+    if isinstance(colors, dict):
+        rows = list(colors.items())
+    else:
+        rows = [(labels if isinstance(labels, str) else "", list(colors))]
+
+    ncols = max((len(c) for _, c in rows), default=0)
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(1.6 + size * ncols, 0.3 + size * len(rows)))
+    else:
+        fig = ax.figure
+    _draw_swatch_rows(ax, rows)
+    ax.set_aspect("equal")
+    return fig
+
+
+def show_palettes(names=None, *, n=10, size=0.42):
+    """First-class palette reference: swatches for every available palette, each
+    tagged with whether it is colorblind-safe, plus a one-line summary footnote.
+
+    ``names`` defaults to :func:`paperplot.available_palettes` (built-in +
+    anything you registered). Returns the ``Figure``.
+    """
+    import matplotlib.pyplot as plt
+    from . import palettes
+
+    if names is None:
+        names = palettes.available_palettes()
+
+    rows, tags = [], []
+    for nm in names:
+        rows.append((nm, palettes.palette(nm, n)))
+        tags.append("colorblind-safe" if palettes.is_colorblind_safe(nm) else "")
+
+    nrows = len(rows)
+    fig_w = 3.8 + size * n          # label gutter + swatches + tag gutter
+    fig_h = 0.7 + size * nrows
+    fig = plt.figure(figsize=(fig_w, fig_h))
+    # Fixed-inch gutters so labels/tags never clip; swatch block fills the middle.
+    left = 1.4 / fig_w
+    ax = fig.add_axes([left, 0.55 / fig_h,
+                       (size * n) / fig_w, (size * nrows) / fig_h])
+    _draw_swatch_rows(ax, rows, tags=tags)
+
+    fig.text(0.5, 0.12 / fig_h,
+             "Green tag = stays distinguishable under color-vision deficiency.   "
+             "muted = fills | bright = strokes (pair them; not for categorical lines).",
+             ha="center", va="bottom", fontsize=7, color="0.35")
+    return fig

paperplot/preview.py

@@ -0,0 +1,250 @@
+"""Notebook preview helpers for small publication figures.
+
+- ``show(fig, zoom)``  : magnify the real figure (SVG) without mutating it.
+- ``preview_in_page``  : embed the figure at true scale in a mock journal page.
+- ``grayscale_proof``  : render desaturated to check APS print legibility.
+"""
+
+from __future__ import annotations
+
+import importlib
+import io
+
+import matplotlib.pyplot as plt
+
+from . import layout
+
+# pp.style() shadows the style submodule on the package; reach it via sys.modules.
+_style = importlib.import_module("paperplot.style")
+
+# Bundled placeholder text (no external 'lorem' dependency).
+LOREM = (
+    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod "
+    "tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, "
+    "quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo "
+    "consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse "
+    "cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non "
+    "proident, sunt in culpa qui officia deserunt mollit anim id est laborum. "
+)
+
+
+def _svg_bytes(fig) -> bytes:
+    buf = io.BytesIO()
+    fig.savefig(buf, format="svg")  # no bbox_inches='tight' -> stable geometry
+    return buf.getvalue()
+
+
+def show(fig, zoom: float = 2.0):
+    """Display ``fig`` magnified by ``zoom`` in a notebook. Figure untouched.
+
+    Renders to SVG (vector, crisp at any zoom) and scales the <svg> width/height.
+    Returns the IPython SVG object (also auto-displays in a notebook).
+    """
+    try:
+        from IPython.display import SVG, display
+    except ImportError as e:  # optional extra: paperplot[notebook]
+        raise ImportError(
+            "show() needs IPython. Install paperplot[notebook] or use "
+            "preview_in_page() (pure matplotlib)."
+        ) from e
+
+    svg = _svg_bytes(fig).decode("utf-8")
+    w_in, h_in = fig.get_size_inches()
+    style_attr = f'style="width:{w_in * zoom:.3f}in;height:{h_in * zoom:.3f}in;"'
+    # inject a sizing style on the first <svg ...> tag
+    svg = svg.replace("<svg ", f"<svg {style_attr} ", 1)
+    obj = SVG(data=svg)
+    display(obj)
+    return obj
+
+
+def _word_width(bg, word, pt, family, renderer, cache):
+    """Measured width of ``word`` in inches (cached)."""
+    if word not in cache:
+        tmp = bg.text(0, -1000, word, fontsize=pt, family=family)
+        cache[word] = tmp.get_window_extent(renderer).width / renderer.dpi
+        tmp.remove()
+    return cache[word]
+
+
+def _wrap_to_width(bg, body, col_w, pt, family, renderer, cache):
+    """Break ``body`` into lines whose *measured* width never exceeds ``col_w``.
+
+    Character-count wrapping (textwrap) can run a word past the column edge when
+    its width estimate is slightly off; measuring each word guarantees every line
+    fits — which also keeps the justification gap non-negative (no overflow).
+    """
+    space_w = max(0.0, (_word_width(bg, "n n", pt, family, renderer, cache)
+                        - _word_width(bg, "nn", pt, family, renderer, cache)))
+    lines, cur, cur_w = [], [], 0.0
+    for word in body.split():
+        ww = _word_width(bg, word, pt, family, renderer, cache)
+        add = ww + (space_w if cur else 0.0)
+        if cur and cur_w + add > col_w:
+            lines.append(" ".join(cur))
+            cur, cur_w = [word], ww
+        else:
+            cur.append(word)
+            cur_w += add
+    if cur:
+        lines.append(" ".join(cur))
+    return lines
+
+
+def _justify_column(bg, x0, y_top, col_w, chunk, pt, family, color,
+                    linespacing, renderer, cache):
+    """Render a column of text fully justified (last line left-aligned)."""
+    line_h = pt / 72.0 * linespacing
+    y = y_top
+    n = len(chunk)
+    for i, line in enumerate(chunk):
+        words = line.split()
+        is_last = i == n - 1
+        if len(words) > 1 and not is_last:
+            widths = [_word_width(bg, w, pt, family, renderer, cache) for w in words]
+            gap = (col_w - sum(widths)) / (len(words) - 1)
+            if 0 <= gap <= col_w:  # sane spacing only
+                x = x0
+                for w, ww in zip(words, widths):
+                    bg.text(x, y, w, fontsize=pt, family=family, color=color,
+                            va="top", ha="left")
+                    x += ww + gap
+                y -= line_h
+                continue
+        bg.text(x0, y, line, fontsize=pt, family=family, color=color,
+                va="top", ha="left")  # ragged fallback / last line
+        y -= line_h
+
+
+def preview_in_page(fig, width="single", *, journal=None, page=(8.5, 11.0),
+                    columns: int = 2, dpi: int = 150, text=None,
+                    body_pt=None, show_info: bool = True, justify: bool = True,
+                    figure_box: bool = False):
+    """Embed ``fig`` at true physical scale inside a mock journal page.
+
+    The surrounding text is real placeholder prose (lorem ipsum by default,
+    override via ``text``) rendered in serif at the journal's body font size
+    (``spec.page_body_pt``), so the figure-to-text scale is faithful. A header
+    lists the journal, column, physical width, and the body/figure font sizes.
+
+    Args:
+        justify: fully justify the body text (default True) so column edges line
+            up with the figure; set False for ragged-right.
+        figure_box: draw the figure's bounding box (default False) — useful to
+            confirm the figure width equals the column width.
+
+    Returns a NEW matplotlib Figure (the proof). True scale holds when the proof
+    is viewed/printed at 100%.
+    """
+    import matplotlib.image as mpimg
+    import matplotlib.patches as mpatches
+
+    spec = _style.resolve_spec(journal)
+    wkey = layout.resolve_width(width)
+    w_lookup = "double" if wkey == "full_page" else wkey
+    body_pt = float(body_pt if body_pt is not None else spec.page_body_pt)
+    page_w, page_h = page
+    fig_w_in, fig_h_in = fig.get_size_inches()
+
+    # Make the mock page geometrically faithful: page columns == journal columns.
+    col_w = layout.mm_to_in(spec.widths_mm["single"])
+    double_w = layout.mm_to_in(spec.widths_mm.get("double", 2 * spec.widths_mm["single"]))
+    gutter = max(0.12, double_w - 2 * col_w) if columns == 2 else 0.2
+    block_w = columns * col_w + (columns - 1) * gutter
+    margin_x = max(0.4, (page_w - block_w) / 2)
+    margin_y = 0.8
+
+    proof = plt.figure(figsize=(page_w, page_h), dpi=dpi)
+    proof.patch.set_facecolor("white")
+    bg = proof.add_axes([0, 0, 1, 1])
+    bg.set_xlim(0, page_w)
+    bg.set_ylim(0, page_h)
+    bg.axis("off")
+    top = page_h - margin_y
+
+    # --- info header: list exactly what this is ---
+    if show_info:
+        w_in = layout.mm_to_in(spec.widths_mm[w_lookup])
+        info = (f"{spec.name}   ·   {wkey} column   ·   "
+                f"{spec.widths_mm[w_lookup]:.0f} mm ({w_in:.2f} in) wide   ·   "
+                f"body {body_pt:g} pt   ·   figure text {spec.font_pt.base:g} pt")
+        bg.text(margin_x, page_h - 0.45, info, fontsize=7, family="sans-serif",
+                color="0.45", va="bottom", ha="left")
+        bg.plot([margin_x, margin_x + block_w], [page_h - 0.52] * 2,
+                color="0.8", lw=0.6)
+
+    # --- embed the real figure at true inches (top of column 0) ---
+    spans = fig_w_in > col_w * 1.5
+    fig_bottom = top - fig_h_in
+    ax_fig = proof.add_axes([margin_x / page_w, fig_bottom / page_h,
+                             fig_w_in / page_w, fig_h_in / page_h])
+    png = io.BytesIO()
+    fig.savefig(png, format="png", dpi=300, facecolor="white")
+    png.seek(0)
+    ax_fig.imshow(mpimg.imread(png))
+    ax_fig.axis("off")
+    if figure_box:
+        bg.add_patch(mpatches.Rectangle(
+            (margin_x, fig_bottom), fig_w_in, fig_h_in,
+            fill=False, edgecolor="0.55", lw=0.8))
+
+    # --- figure caption (serif, italic, at figure text size) ---
+    cap_pt = spec.font_pt.base
+    cap_y = fig_bottom - 0.07
+    bg.text(margin_x, cap_y,
+            f"FIG. 1. Placeholder figure shown at true {wkey}-column scale.",
+            fontsize=cap_pt, family="serif", style="italic",
+            va="top", ha="left", color="0.2")
+    after_caption = cap_y - cap_pt / 72.0 * 1.7 - 0.08
+
+    # --- body text: real lorem ipsum at the journal body size, flowing columns ---
+    body = text if text is not None else (LOREM * 14)
+    linespacing = 1.45
+    line_h = body_pt / 72.0 * linespacing
+
+    # a renderer is needed to measure word widths (for wrapping + justification)
+    proof.canvas.draw()
+    renderer = proof.canvas.get_renderer()
+    cache: dict = {}
+    # Wrap by measured width so no word ever spills past the column edge.
+    lines = _wrap_to_width(bg, body, col_w, body_pt, "serif", renderer, cache)
+
+    idx = 0
+    for c in range(columns):
+        x0 = margin_x + c * (col_w + gutter)
+        if spans:
+            col_top = after_caption
+        else:
+            col_top = after_caption if c == 0 else top
+        nfit = max(0, int((col_top - margin_y) / line_h))
+        chunk = lines[idx:idx + nfit]
+        idx += nfit
+        if not chunk:
+            continue
+        if justify:
+            _justify_column(bg, x0, col_top, col_w, chunk, body_pt, "serif",
+                            "0.15", linespacing, renderer, cache)
+        else:
+            bg.text(x0, col_top, "\n".join(chunk), fontsize=body_pt,
+                    family="serif", color="0.15", va="top", ha="left",
+                    linespacing=linespacing)
+    return proof
+
+
+def grayscale_proof(fig, dpi: int = 200):
+    """Return a NEW figure showing ``fig`` desaturated (APS print reality)."""
+    import numpy as np
+    import matplotlib.image as mpimg
+
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", dpi=dpi, facecolor="white")
+    buf.seek(0)
+    rgb = mpimg.imread(buf)[..., :3]
+    gray = rgb @ np.array([0.2126, 0.7152, 0.0722])
+
+    w_in, h_in = fig.get_size_inches()
+    proof = plt.figure(figsize=(w_in, h_in), dpi=dpi)
+    ax = proof.add_axes([0, 0, 1, 1])
+    ax.imshow(gray, cmap="gray", vmin=0, vmax=1)
+    ax.axis("off")
+    return proof

paperplot/registry.py

@@ -0,0 +1,111 @@
+"""Load journal specs from ``data/journals.toml`` into ``JournalSpec`` objects.
+
+This is the layer between TOML and the frozen dataclasses: it reads the data
+file via ``importlib.resources``, coerces types (TOML lists -> tuples), merges
+variant overrides over their base, validates, and caches the result.
+"""
+
+from __future__ import annotations
+
+import difflib
+from functools import lru_cache
+from importlib.resources import files
+from typing import Dict
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10 backport
+    import tomli as tomllib  # type: ignore
+
+from .journals import FontScale, JournalSpec
+
+_REQUIRED = {
+    "name",
+    "revision",
+    "widths_mm",
+    "page_height_mm",
+    "caption_reserve_mm",
+    "min_linewidth_pt",
+    "font_family",
+    "font_pt",
+    "rasterize_dpi",
+}
+
+
+def _read_data() -> dict:
+    text = files("paperplot").joinpath("data", "journals.toml").read_text("utf-8")
+    return tomllib.loads(text)
+
+
+def _deep_merge(base: dict, over: dict) -> dict:
+    """Recursively merge ``over`` onto ``base`` so a variant can override a single
+    nested field (e.g. font_pt.base) without dropping its siblings."""
+    out = dict(base)
+    for k, v in over.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _build_spec(d: dict) -> JournalSpec:
+    missing = _REQUIRED - d.keys()
+    if missing:
+        raise ValueError(f"Journal spec {d.get('name', '?')!r} missing keys: {sorted(missing)}")
+    return JournalSpec(
+        name=d["name"],
+        revision=d["revision"],
+        widths_mm={k: float(v) for k, v in d["widths_mm"].items()},
+        page_height_mm=float(d["page_height_mm"]),
+        caption_reserve_mm=float(d["caption_reserve_mm"]),
+        font_family=tuple(d["font_family"]),  # TOML list -> tuple
+        font_pt=FontScale(**d["font_pt"]),
+        min_linewidth_pt=float(d["min_linewidth_pt"]),
+        page_body_pt=float(d.get("page_body_pt", 10.0)),
+        rasterize_dpi={k: int(v) for k, v in d["rasterize_dpi"].items()},
+    )
+
+
+@lru_cache(maxsize=1)
+def _registry() -> Dict[str, JournalSpec]:
+    data = _read_data()
+    specs: Dict[str, JournalSpec] = {}
+    for key, raw in data.get("journal", {}).items():
+        variants = raw.pop("variants", {}) if isinstance(raw, dict) else {}
+        base = _build_spec(raw)
+        specs[key.lower()] = base
+        for vkey, override in variants.items():
+            # deep per-field override so a partial nested table (e.g. just
+            # font_pt.base) keeps the base journal's sibling values.
+            merged = _deep_merge(raw, override)
+            specs[vkey.lower()] = _build_spec(merged)
+    return specs
+
+
+def available() -> list[str]:
+    """Sorted list of known journal keys (including variants)."""
+    return sorted(_registry())
+
+
+def get_spec(key: str) -> JournalSpec:
+    """Look up a spec by key, e.g. ``"aps"`` or ``"prl"``.
+
+    A ``"key@revision"`` suffix is accepted and validated against the spec's
+    own revision (reproducibility pin).
+    """
+    name, _, revision = str(key).strip().lower().partition("@")
+    reg = _registry()
+    try:
+        spec = reg[name]
+    except KeyError:
+        hint = difflib.get_close_matches(name, reg, n=1)
+        suffix = f" Did you mean {hint[0]!r}?" if hint else ""
+        raise KeyError(
+            f"Unknown journal {key!r}. Available: {available()}.{suffix}"
+        ) from None
+    if revision and revision != spec.revision.lower():
+        raise ValueError(
+            f"Journal {name!r} is revision {spec.revision!r}, not {revision!r}."
+        )
+    return spec