ipyrowtable 0.1.1__py3-none-any.whl

ipyrowtable/__init__.py

@@ -0,0 +1,53 @@
+"""ipyrowtable: editable ipywidgets tables of elements in series.
+
+Each row is an element (a layer, a pipe segment, a cable run, ...) with input columns the
+user edits and output columns your compute function fills in. Rows can be added and
+removed, values *between* rows (temperatures at interfaces, pressures at joints) get their
+own column with editable boundary conditions, and an optional toggle switches unit systems.
+
+    from ipyrowtable import RowTable, NumberColumn, OutputColumn
+
+    table = RowTable(
+        columns=[NumberColumn("x", "x", default=1.0), OutputColumn("x2", "x²")],
+        compute=lambda inputs: {"x2": inputs.column("x") ** 2},
+    )
+    table
+
+See the example notebooks, and ipyrowtable.examples.conduction for a complete application.
+"""
+
+from .columns import (
+    ChoiceColumn,
+    Column,
+    InputColumn,
+    NodeColumn,
+    NumberColumn,
+    OutputColumn,
+    TextColumn,
+)
+from .figure import LiveFigure
+from .formatting import fmt_sig
+from .layout import side_by_side
+from .table import RowTable, TableInputs, TableResults
+from .units import Unit, UnitSystem
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "RowTable",
+    "TableInputs",
+    "TableResults",
+    "Column",
+    "InputColumn",
+    "ChoiceColumn",
+    "NumberColumn",
+    "TextColumn",
+    "OutputColumn",
+    "NodeColumn",
+    "Unit",
+    "UnitSystem",
+    "LiveFigure",
+    "side_by_side",
+    "fmt_sig",
+    "__version__",
+]

ipyrowtable/columns.py

@@ -0,0 +1,265 @@
+"""Column types for RowTable.
+
+Input columns (edited by the user):   ChoiceColumn, NumberColumn, TextColumn
+Output columns (filled by compute):   OutputColumn, NodeColumn
+
+Input columns can also be used as table-wide *parameters* (shown above the table).
+To make a new input type, subclass InputColumn and implement ``create_widget``; override
+``to_display``, ``to_base`` and ``refresh`` if the widget shows something other than the
+stored value.
+"""
+
+from __future__ import annotations
+
+import math
+
+import ipywidgets as widgets
+
+from .formatting import formatter, right_aligned, tidy
+
+__all__ = [
+    "Column",
+    "InputColumn",
+    "NumberColumn",
+    "ChoiceColumn",
+    "TextColumn",
+    "OutputColumn",
+    "NodeColumn",
+]
+
+
+class _UnitLabels(dict):
+    """format_map helper: {unit} is the column's own unit, {<quantity>} any quantity's unit."""
+
+    def __init__(self, units, quantity):
+        super().__init__()
+        self.units, self.quantity = units, quantity
+
+    def __missing__(self, key):
+        return self.units.label(self.quantity if key == "unit" else key)
+
+
+class Column:
+    """Base class for all columns.
+
+    key     identifies the column in rows, compute outputs and results
+    header  string shown at the top; may use {unit} for this column's unit or {<quantity>}
+            for any other quantity's unit, e.g. "Material (k in {conductivity})".
+            Can also be a callable(units) -> str.
+    width   CSS width of the grid column
+    """
+
+    width = "120px"
+    quantity = None
+
+    def __init__(self, key: str, header=None, width: str | None = None):
+        self.key = key
+        self.header = key if header is None else header
+        if width is not None:
+            self.width = width
+
+    def header_text(self, units) -> str:
+        if callable(self.header):
+            return self.header(units)
+        return self.header.format_map(_UnitLabels(units, self.quantity))
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.key!r})"
+
+
+class InputColumn(Column):
+    """Base for editable columns and parameters. Values are held in base units.
+
+    default  value for new rows, in base units; or a dict {unit-system name: display value}
+             for defaults that are round numbers in each system.
+    """
+
+    def __init__(self, key, header=None, default=None, width=None):
+        super().__init__(key, header, width)
+        self.default = default
+
+    def default_value(self, units):
+        """The default in base units, for the given unit system."""
+        if isinstance(self.default, dict):
+            return self.to_base(self.default[units.name], units)
+        return self.default
+
+    def to_display(self, value, units):
+        """Convert a stored (base) value to what the widget shows."""
+        return value
+
+    def to_base(self, value, units):
+        """Convert a widget value to the stored (base) value."""
+        return value
+
+    def create_widget(self, value, units):
+        """Return a new widget showing `value` (base units). Must have a `value` trait."""
+        raise NotImplementedError
+
+    def refresh(self, widget, value, units):
+        """Show `value` (base units) in `widget` after a unit-system change."""
+        widget.value = self.to_display(value, units)
+
+    def validate(self, value):
+        """Check a saved value (base units) before it is restored; return it, possibly
+        normalized, or raise ValueError. The default accepts anything."""
+        return value
+
+
+class NumberColumn(InputColumn):
+    """A number per row.
+
+    quantity  name of the quantity in your UnitSystems (e.g. "length"); None = unitless
+    min, max  bounds in base units; if either is given the box clamps to them
+    """
+
+    def __init__(self, key, header=None, quantity=None, default=0.0, min=None, max=None,
+                 width=None):
+        super().__init__(key, header, default, width)
+        self.quantity, self.min, self.max = quantity, min, max
+
+    def to_display(self, value, units):
+        return tidy(units.to_display(self.quantity, value))
+
+    def to_base(self, value, units):
+        return float(units.to_base(self.quantity, value))
+
+    def _bounds(self, units):
+        lo = -1e300 if self.min is None else units.to_display(self.quantity, self.min)
+        hi = 1e300 if self.max is None else units.to_display(self.quantity, self.max)
+        return lo, hi
+
+    def create_widget(self, value, units):
+        layout = widgets.Layout(width="100%")
+        if self.min is None and self.max is None:
+            return widgets.FloatText(value=self.to_display(value, units), layout=layout)
+        lo, hi = self._bounds(units)
+        return widgets.BoundedFloatText(
+            value=self.to_display(value, units), min=lo, max=hi, step=None, layout=layout
+        )
+
+    def refresh(self, widget, value, units):
+        if isinstance(widget, widgets.BoundedFloatText):
+            lo, hi = self._bounds(units)
+            with widget.hold_trait_notifications():
+                widget.min, widget.max = lo, hi
+        widget.value = self.to_display(value, units)
+
+    def validate(self, value):
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError(f"{self.key}: expected a number, got {value!r}")
+        value = float(value)
+        if not math.isfinite(value):
+            raise ValueError(f"{self.key}: {value} is not a finite number")
+        # allow for round-off from converting through display units
+        if self.min is not None and value < self.min - 1e-9 * max(1.0, abs(self.min)):
+            raise ValueError(f"{self.key}: {value:g} is below the minimum {self.min:g}")
+        if self.max is not None and value > self.max + 1e-9 * max(1.0, abs(self.max)):
+            raise ValueError(f"{self.key}: {value:g} is above the maximum {self.max:g}")
+        return value
+
+
+class ChoiceColumn(InputColumn):
+    """A dropdown; the row value is the chosen option's key.
+
+    options  dict {key: data} or a list of keys. The data (e.g. a material property) is
+             available to your compute function via the column's `options` dict.
+    label    optional callable(key, data, units) -> str for the dropdown text, e.g. to show
+             a property of each option in the current units
+    default  initially selected key (default: the first)
+    """
+
+    width = "250px"
+
+    def __init__(self, key, header=None, options=(), label=None, default=None, width=None):
+        options = dict(options) if isinstance(options, dict) else {k: k for k in options}
+        if not options:
+            raise ValueError(f"ChoiceColumn {key!r} needs at least one option.")
+        super().__init__(key, header, next(iter(options)) if default is None else default, width)
+        self.options, self.label = options, label
+
+    def _choices(self, units):
+        if self.label is None:
+            return list(self.options)
+        return [(self.label(k, v, units), k) for k, v in self.options.items()]
+
+    def create_widget(self, value, units):
+        if value not in self.options:
+            raise ValueError(f"{value!r} is not one of the {self.key!r} options.")
+        return widgets.Dropdown(
+            options=self._choices(units), value=value, layout=widgets.Layout(width="100%")
+        )
+
+    def refresh(self, widget, value, units):
+        if self.label is not None:
+            widget.options = self._choices(units)  # this resets the selection...
+        widget.value = value  # ...so restore it
+
+    def validate(self, value):
+        if value not in self.options:
+            raise ValueError(f"{self.key}: {value!r} is not one of the options")
+        return value
+
+
+class TextColumn(InputColumn):
+    """Free text per row (e.g. a name or tag); updates when the box loses focus."""
+
+    width = "160px"
+
+    def __init__(self, key, header=None, default="", width=None):
+        super().__init__(key, header, default, width)
+
+    def create_widget(self, value, units):
+        return widgets.Text(
+            value=value, continuous_update=False, layout=widgets.Layout(width="100%")
+        )
+
+    def validate(self, value):
+        if not isinstance(value, str):
+            raise ValueError(f"{self.key}: expected text, got {value!r}")
+        return value
+
+
+class OutputColumn(Column):
+    """One computed value per row, shown right-aligned.
+
+    quantity  name of the quantity in your UnitSystems, for conversion and {unit} in headers
+    fmt       None (4 significant figures), a format string like "{:.2f}", or a callable
+    """
+
+    width = "150px"
+
+    def __init__(self, key, header=None, quantity=None, fmt=None, width=None):
+        super().__init__(key, header, width)
+        self.quantity, self.format = quantity, formatter(fmt)
+
+    def render(self, value, units) -> str:
+        return right_aligned(self.format(units.to_display(self.quantity, value)))
+
+
+class NodeColumn(OutputColumn):
+    """Computed values *between* rows: n + 1 values for n rows.
+
+    The first value belongs to the top/inlet, shown in a leading row above the first element;
+    each row then shows the value at its bottom/outlet face.
+
+    inputs         which ends are editable boundary conditions: ("first", "last") (default),
+                   "first", "last" or ()
+    first_default  default for the first end, in base units, or {unit-system name: value}
+    last_default   the same for the last end
+    min, max       bounds for the editable ends, in base units
+    """
+
+    width = "120px"
+
+    def __init__(self, key, header=None, quantity=None, inputs=("first", "last"),
+                 first_default=0.0, last_default=0.0, min=None, max=None, fmt=None, width=None):
+        super().__init__(key, header, quantity, fmt, width)
+        inputs = (inputs,) if isinstance(inputs, str) else tuple(inputs)
+        if set(inputs) - {"first", "last"}:
+            raise ValueError("NodeColumn inputs must be drawn from 'first' and 'last'.")
+        self.inputs = inputs
+        self.ends = {
+            "first": NumberColumn(key, quantity=quantity, default=first_default, min=min, max=max),
+            "last": NumberColumn(key, quantity=quantity, default=last_default, min=min, max=max),
+        }

ipyrowtable/examples/__init__.py

@@ -0,0 +1,4 @@
+"""Complete example applications built with ipyrowtable.
+
+conduction   steady conduction through a plane composite wall, with units and a profile plot
+"""

ipyrowtable/examples/conduction.py

@@ -0,0 +1,340 @@
+"""
+Steady-state conduction through a stack of flat plates (a plane composite wall).
+
+A complete ipyrowtable application: a layer table (material and thickness in; conductance and
+interface temperature out) with an SI / Imperial toggle and a live temperature-profile plot.
+
+    from ipyrowtable.examples.conduction import layer_stack_app
+    app = layer_stack_app(units="SI")        # table and profile plot side by side
+    app
+
+    app.stack.results["q"]                    # heat flux, W/m² (base units)
+    app.stack.results.display("q")            # the same in the units currently shown
+    app.stack.results.display("temperature")  # interface temperatures, top surface first
+    app.stack.units = "Imperial"              # same as clicking the toggle
+
+To use your own solver, pass solver=your_function to LayerStack or layer_stack_app; it must
+have the same signature and return values as `solve_series_conduction` (SI in and out).
+The plot needs matplotlib (pip install ipyrowtable[plot]).
+"""
+
+import numpy as np
+
+from .. import (
+    ChoiceColumn,
+    LiveFigure,
+    NodeColumn,
+    NumberColumn,
+    OutputColumn,
+    RowTable,
+    Unit,
+    UnitSystem,
+    fmt_sig,
+    side_by_side,
+)
+
+__all__ = [
+    "MATERIALS",
+    "SI",
+    "IMPERIAL",
+    "UNIT_SYSTEMS",
+    "solve_series_conduction",
+    "LayerStack",
+    "TemperatureProfilePlot",
+    "layer_stack_app",
+]
+
+# Thermal conductivities near 300 K, in W/(m·K). Edit or extend freely (always SI here).
+MATERIALS = {
+    "Copper": 401.0,
+    "Aluminum": 237.0,
+    "Carbon steel": 60.5,
+    "Stainless steel (304)": 14.9,
+    "Concrete": 1.4,
+    "Glass": 1.4,
+    "Brick": 0.72,
+    "Gypsum board": 0.17,
+    "Wood (softwood)": 0.12,
+    "Fiberglass insulation": 0.04,
+    "Polystyrene foam": 0.03,
+}
+
+# ------------------------------------------------------------------------------ units
+# Base units (what the solver uses): m, °C, W/m·K, W/m²·K, W/m², m²·K/W.
+
+_W_TO_BTU_PER_HR = 1.0 / 0.29307107  # 1 W = 3.4121 Btu/hr (International Table Btu)
+_M_TO_FT = 1.0 / 0.3048
+_CONDUCTANCE_TO_IMPERIAL = _W_TO_BTU_PER_HR / _M_TO_FT**2 / 1.8
+
+SI = UnitSystem("SI", {
+    "length": Unit("mm", 1000.0),
+    "temperature": Unit("°C"),
+    "conductivity": Unit("W/m·K"),
+    "conductance": Unit("W/m²·K"),
+    "heat_flux": Unit("W/m²"),
+    "resistance": Unit("m²·K/W"),
+})
+
+IMPERIAL = UnitSystem("Imperial", {
+    "length": Unit("in", 1.0 / 0.0254),
+    "temperature": Unit("°F", 1.8, 32.0),
+    "conductivity": Unit("Btu/hr·ft·°F", _W_TO_BTU_PER_HR / _M_TO_FT / 1.8),
+    "conductance": Unit("Btu/hr·ft²·°F", _CONDUCTANCE_TO_IMPERIAL),
+    "heat_flux": Unit("Btu/hr·ft²", _W_TO_BTU_PER_HR / _M_TO_FT**2),
+    "resistance": Unit("hr·ft²·°F/Btu", 1.0 / _CONDUCTANCE_TO_IMPERIAL),
+})
+
+UNIT_SYSTEMS = {"SI": SI, "Imperial": IMPERIAL}
+
+# Starting layers, (material, thickness in that system's display units).
+DEFAULT_LAYERS = {
+    "SI": (("Carbon steel", 10.0), ("Fiberglass insulation", 50.0)),
+    "Imperial": (("Carbon steel", 0.375), ("Fiberglass insulation", 2.0)),
+}
+
+
+# ------------------------------------------------------------------------------ solver
+
+
+def solve_series_conduction(thicknesses, conductivities, T_top, T_bottom):
+    """Steady 1-D conduction through flat plates in series, per unit area (all SI).
+
+    Parameters
+    ----------
+    thicknesses : sequence of float
+        Layer thicknesses in m, ordered top to bottom.
+    conductivities : sequence of float
+        Thermal conductivity of each layer, W/(m·K).
+    T_top, T_bottom : float
+        Boundary surface temperatures, °C.
+
+    Returns
+    -------
+    conductances : ndarray, shape (n,)
+        Layer conductance k/L, W/(m²·K).
+    temperatures : ndarray, shape (n + 1,)
+        Interface temperatures in °C, top surface first, bottom surface last.
+    q : float
+        Heat flux in W/m², positive from top to bottom.
+    """
+    L = np.asarray(thicknesses, dtype=float)
+    k = np.asarray(conductivities, dtype=float)
+    conductances = k / L
+    resistances = 1.0 / conductances
+    q = (T_top - T_bottom) / resistances.sum()
+    temperatures = T_top - q * np.concatenate(([0.0], np.cumsum(resistances)))
+    return conductances, temperatures, q
+
+
+# ------------------------------------------------------------------------------ the table
+
+
+class LayerStack(RowTable):
+    """The layer table: material and thickness in; conductance and interface temperature out."""
+
+    def __init__(self, layers=None, T_top=None, T_bottom=None, units="SI", materials=None,
+                 solver=solve_series_conduction, persist=None, persist_file=None):
+        """
+        layers    : iterable of (material_name, thickness), top to bottom, in `units`
+                    (mm for SI, inches for Imperial). Defaults to a steel + insulation example.
+        T_top     : top boundary temperature in `units` (default 100 °C / 212 °F)
+        T_bottom  : bottom boundary temperature in `units` (default 20 °C / 68 °F)
+        units     : "SI" or "Imperial" (the toggle can change it later)
+        materials : dict {name: k in W/(m·K)}; defaults to MATERIALS
+        solver    : function(thicknesses_m, k, T_top_C, T_bottom_C) -> (conductances, temps_C, q)
+        persist   : key to save the inputs under between sessions (see RowTable); the
+                    arguments above are then the initial values
+        persist_file : where to save; default beside the notebook
+        """
+        self.materials = dict(materials or MATERIALS)
+        self.solver = solver
+        if layers is None:
+            layers = DEFAULT_LAYERS[units]
+
+        super().__init__(
+            columns=[
+                ChoiceColumn(
+                    "material",
+                    "Material <span style='font-weight:normal; color:gray'>"
+                    "(k in {conductivity})</span>",
+                    options=self.materials,
+                    label=lambda name, k, u: f"{name}  (k = {u.to_display('conductivity', k):.3g})",
+                    width="280px",
+                ),
+                NumberColumn("thickness", "Thickness ({unit})", quantity="length",
+                             default={"SI": 10.0, "Imperial": 0.5}, min=0.0, width="120px"),
+                OutputColumn("conductance", "Conductance ({unit})", quantity="conductance",
+                             width="200px"),
+                NodeColumn("temperature", "Temperature ({unit})", quantity="temperature",
+                           first_default=100.0, last_default=20.0, fmt="{:.2f}", width="120px"),
+            ],
+            compute=self._compute,
+            rows=[{"material": m, "thickness": t} for m, t in layers],
+            edges={"temperature": (T_top, T_bottom)},
+            unit_systems=UNIT_SYSTEMS,
+            units=units,
+            leading_label="— top surface —",
+            item_name="layer",
+            summary=self._summary,
+            output_quantities={"q": "heat_flux", "R_total": "resistance", "U_total": "conductance"},
+            persist=persist,
+            persist_file=persist_file,
+        )
+
+    def _compute(self, inputs):
+        L = inputs.column("thickness").astype(float)
+        if np.any(L <= 0):
+            raise ValueError("Every layer needs a thickness greater than zero.")
+        k = np.array([self.materials[m] for m in inputs.column("material")])
+        T_top, T_bottom = inputs.edges["temperature"]
+        conductance, temperature, q = self.solver(L, k, T_top, T_bottom)
+        R_total = float(np.sum(1.0 / np.asarray(conductance, dtype=float)))
+        return {
+            "conductance": conductance,
+            "temperature": temperature,
+            "q": float(q),
+            "R_total": R_total,
+            "U_total": 1.0 / R_total,
+        }
+
+    @staticmethod
+    def _summary(results):
+        u = results.units
+        return (
+            f"Heat flux q = <b>{fmt_sig(results.display('q'))} {u.label('heat_flux')}</b>"
+            " (positive top → bottom)"
+            f" &nbsp;·&nbsp; total resistance = {fmt_sig(results.display('R_total'))}"
+            f" {u.label('resistance')}"
+            f" &nbsp;·&nbsp; overall U = {fmt_sig(results.display('U_total'))}"
+            f" {u.label('conductance')}"
+        )
+
+    # conveniences
+    @property
+    def T_top(self):
+        """The top-temperature input widget."""
+        return self.edge_widget("temperature", "first")
+
+    @property
+    def T_bottom(self):
+        """The bottom-temperature input widget."""
+        return self.edge_widget("temperature", "last")
+
+    @property
+    def layers(self):
+        """Current stack as a list of (material, thickness in display units), top to bottom."""
+        return [(row["material"], row["thickness"]) for row in self.rows]
+
+
+# ------------------------------------------------------------------------------ the profile plot
+
+_PLOT_THEMES = {
+    "light": dict(
+        surface="#fcfcfb", ink="#0b0b0b", secondary="#52514e", muted="#898781",
+        grid="#e1e0d9", axis="#c3c2b7", line="#2a78d6", bands=("#f0efec", "#e6e5e0"),
+    ),
+    "dark": dict(
+        surface="#1a1a19", ink="#ffffff", secondary="#c3c2b7", muted="#898781",
+        grid="#2c2c2a", axis="#383835", line="#3987e5", bands=("#242422", "#2e2e2b"),
+    ),
+}
+
+
+def _spread(centers, gap, limit):
+    """Nudge label positions apart so neighbours are at least `gap` apart, within [gap/2, limit]."""
+    y = [max(c, gap / 2) for c in centers]
+    for i in range(1, len(y)):
+        y[i] = max(y[i], y[i - 1] + gap)
+    if y and y[-1] > limit:
+        y[-1] = limit
+        for i in range(len(y) - 2, -1, -1):
+            y[i] = min(y[i], y[i + 1] - gap)
+    return y
+
+
+class TemperatureProfilePlot(LiveFigure):
+    """Temperature-vs-depth plot for a LayerStack; redraws itself on every change.
+
+    size  : figure size in inches (width, height)
+    theme : "light" or "dark", to match your notebook theme
+    dpi   : render resolution; 200 is crisp on hi-DPI screens
+    """
+
+    def __init__(self, stack, size=(6.8, 4.4), theme="light", dpi=200):
+        self.colors = _PLOT_THEMES[theme]
+        super().__init__(stack, size=size, dpi=dpi, facecolor=self.colors["surface"])
+
+    def draw(self, fig, results):
+        c = self.colors
+        u = results.units
+        ax = fig.add_axes([0.13, 0.13, 0.55, 0.70], facecolor=c["surface"])
+        for side in ("top", "right"):
+            ax.spines[side].set_visible(False)
+        for side in ("left", "bottom"):
+            ax.spines[side].set_color(c["axis"])
+        ax.tick_params(colors=c["axis"], labelcolor=c["secondary"], labelsize=9, length=3)
+
+        depth = np.concatenate(([0.0], np.cumsum(results.display("thickness"))))
+        T = np.asarray(results.display("temperature"))
+        total = depth[-1]
+
+        # Layers as alternating neutral bands, separated by a thin surface-colored gap.
+        for i in range(len(depth) - 1):
+            ax.axhspan(depth[i], depth[i + 1], color=c["bands"][i % 2], lw=0, zorder=0)
+        for y in depth[1:-1]:
+            ax.axhline(y, color=c["surface"], lw=1.5, zorder=1)
+        ax.grid(axis="x", color=c["grid"], lw=0.75)
+        ax.set_axisbelow(True)
+
+        # The temperature profile: straight within each layer, kinked at interfaces.
+        ax.plot(T, depth, color=c["line"], lw=2, solid_joinstyle="round", solid_capstyle="round",
+                marker="o", ms=7, mfc=c["line"], mec=c["surface"], mew=1.5, zorder=3, clip_on=False)
+
+        lo, hi = float(T.min()), float(T.max())
+        pad = 0.08 * (hi - lo) if hi > lo else 1.0
+        ax.set_xlim(lo - pad, hi + pad)
+        ax.set_ylim(total, 0)  # top surface at the top
+        ax.set_xlabel(f"Temperature ({u.label('temperature')})", color=c["secondary"], fontsize=9.5)
+        ax.set_ylabel(f"Depth from top surface ({u.label('length')})", color=c["secondary"],
+                      fontsize=9.5)
+
+        ax.set_title("Temperature profile", loc="left", fontsize=11, color=c["ink"],
+                     fontweight="bold", pad=22)
+        q = results.display("q")
+        direction = "top → bottom" if q >= 0 else "bottom → top"
+        ax.text(0, 1.03, f"Heat flux {fmt_sig(abs(q))} {u.label('heat_flux')}, {direction}",
+                transform=ax.transAxes, fontsize=9, color=c["secondary"], va="bottom")
+
+        # Material names in the right margin, with leader lines so thin layers stay readable.
+        fontsize = 9
+        axes_height_pt = fig.get_figheight() * ax.get_position().height * 72
+        gap = 1.35 * fontsize * total / axes_height_pt
+        centers = (depth[:-1] + depth[1:]) / 2
+        for name, y_band, y_label in zip(results["material"], centers,
+                                         _spread(centers, gap, total - gap / 2), strict=True):
+            ax.annotate(
+                name,
+                xy=(1.0, y_band), xycoords=("axes fraction", "data"),
+                xytext=(1.05, y_label), textcoords=("axes fraction", "data"),
+                ha="left", va="center", fontsize=fontsize, color=c["secondary"],
+                arrowprops=dict(arrowstyle="-", color=c["muted"], lw=0.75, shrinkA=2, shrinkB=0),
+                annotation_clip=False,
+            )
+
+
+# ------------------------------------------------------------------------------ convenience
+
+
+def layer_stack_app(plot_options=None, **stack_options):
+    """A LayerStack and its TemperatureProfilePlot side by side (wrapping on narrow screens).
+
+    stack_options go to LayerStack (layers, T_top, T_bottom, units, materials, solver);
+    plot_options go to TemperatureProfilePlot (size, theme, dpi).
+    The returned box has .stack and .plot attributes.
+    """
+    stack = LayerStack(**stack_options)
+    plot = TemperatureProfilePlot(stack, **(plot_options or {}))
+    app = side_by_side(stack, plot)
+    app.stack, app.plot = stack, plot
+    return app
+