labforge 0.1.0__py3-none-any.whl

labforge/__init__.py

@@ -0,0 +1,17 @@
+"""
+labforge: wrap plain Python functions into a small scientific desktop app,
+following the theory -> simulation -> visualization -> analysis workflow.
+
+Lab collects the registrations and launches the app; Param specifies a kwarg's
+control; ScanResult is what a parameter scan hands to viz and analysis
+functions; style is the optional house figure treatment; palette exposes the
+active theme's colours; themes lists what open(theme=...) accepts.
+"""
+
+from .figures import palette, style
+from .lab import Lab
+from .param import Param
+from .scan import ScanResult
+from .theme import names as themes
+
+__all__ = ["Lab", "Param", "ScanResult", "style", "palette", "themes"]

labforge/controls.py

@@ -0,0 +1,278 @@
+"""
+Param -> a Flet control row plus a read() closure for its current value.
+"""
+
+from dataclasses import dataclass
+
+import flet as ft
+
+from .ui import FONT_MONO
+
+# Parameter names and values are data, so every label, readout and field in a
+# control row speaks the app's monospace voice.
+MONO = ft.TextStyle(size=13, font_family=FONT_MONO)
+MONO_LABEL = ft.TextStyle(size=12, font_family=FONT_MONO)
+
+
+@dataclass
+class ControlBinding:
+    """
+    One built control row and its value accessor.
+
+    Parameters
+    ----------
+    row: Control
+        The labelled row to place in the page tree.
+    read: callable
+        Zero-arg closure returning the current parsed value (scalar, tuple,
+        or list of scan values).
+    """
+
+    row: object
+    read: callable
+
+
+def build_control(name, param, values, page):
+    """
+    Build the control row for one Param.
+
+    Every control commits to values as it changes, so edits survive navigation
+    even before the next Run; read() is also what Run, Render and Compute pull.
+
+    Parameters
+    ----------
+    name: str
+        The kwarg name; keys the values dict and labels the row by default.
+    param: Param
+        The normalized spec (default resolved, step filled for bounded kinds).
+    values: dict
+        The live values dict (state.worker_values or a per-tab kwargs dict);
+        read at build time and committed to on every change.
+    page: ft.Page
+        Needed to flush live readout updates during a slider drag.
+
+    Returns
+    -------
+    ControlBinding for the row.
+    """
+    label = param.label or name
+    value = values.get(name, param.default)
+    if param.kind == "tuple":
+        return tuple_control(name, label, param, value, values)
+    if param.bounds is None and not param.scan:
+        return text_control(name, label, param, value, values)
+    if param.bounds is None:
+        return scan_control(name, label, param, value, values)
+    if not param.scan:
+        return slider_control(name, label, param, value, values, page)
+    return toggled_control(name, label, param, value, values, page)
+
+
+def slider_control(name, label, param, value, values, page):
+    """A bounded param: a slider with a live readout."""
+    lo, hi = param.bounds
+    if isinstance(value, list):  # scan values left over from a stale spec edit
+        value = param.default
+    # Built here and returned inside the tree, so it is mounted before any drag
+    # fires; on_change mutates it and flushes via page.update(), never
+    # readout.update(), which Flet 0.86 drops.
+    readout = ft.Text(format_scalar(param, value), width=64, style=MONO)
+    slider = ft.Slider(
+        min=lo,
+        max=hi,
+        divisions=max(1, round((hi - lo) / param.step)),
+        value=value,
+        label="{value}",
+    )
+
+    def on_change(e):
+        readout.value = format_scalar(param, cast(param, e.control.value))
+        page.update()
+
+    def on_commit(e):
+        values[name] = cast(param, e.control.value)
+
+    slider.on_change = on_change
+    slider.on_change_end = on_commit  # commit on release, not on every frame
+
+    def read():
+        return cast(param, slider.value)
+
+    return ControlBinding(row=slider_row(label, slider, readout), read=read)
+
+
+def text_control(name, label, param, value, values):
+    """An unbounded scalar or int: a validated text field."""
+    field = ft.TextField(
+        label=label,
+        value=format_scalar(param, value),
+        width=160,
+        text_style=MONO,
+        label_style=MONO_LABEL,
+    )
+
+    def read():
+        parsed = parse_scalar(param, field.value, fallback=values.get(name, param.default))
+        values[name] = parsed
+        return parsed
+
+    field.on_change = lambda e: read()
+    return ControlBinding(row=field, read=read)
+
+
+def scan_control(name, label, param, value, values):
+    """An unbounded scan param: always a comma-separated values field."""
+    field = ft.TextField(
+        label=f"{label} (comma-separated to scan)",
+        value=format_values(param, value),
+        width=260,
+        text_style=MONO,
+        label_style=MONO_LABEL,
+    )
+
+    def read():
+        parsed = parse_values(param, field.value, fallback=values.get(name, param.default))
+        values[name] = parsed
+        return parsed
+
+    field.on_change = lambda e: read()
+    return ControlBinding(row=field, read=read)
+
+
+def toggled_control(name, label, param, value, values, page):
+    """
+    A bounded scan param: a slider row with a scan Switch.
+
+    The switch swaps the content of a mounted Container between the slider and a
+    comma-list field — the same mutate-in-place pattern the pages use for their
+    result panes. Starting from a list value (a scan committed earlier) restores
+    scan mode.
+    """
+    scanning = isinstance(value, list)
+    slider_binding = slider_control(
+        name, label, param, value if not scanning else param.default, values, page
+    )
+    field = ft.TextField(
+        label=f"{label} values",
+        value=format_values(param, value),
+        width=220,
+        text_style=MONO,
+        label_style=MONO_LABEL,
+    )
+    holder = ft.Container(content=field if scanning else slider_binding.row, expand=True)
+    switch = ft.Switch(label="SCAN", value=scanning, label_position=ft.LabelPosition.RIGHT)
+
+    def read():
+        if switch.value:
+            parsed = parse_values(param, field.value, fallback=values.get(name, param.default))
+        else:
+            parsed = slider_binding.read()
+        values[name] = parsed
+        return parsed
+
+    def on_toggle(e):
+        if switch.value:
+            # Carry the slider's value across, so switching to scan starts there.
+            field.value = format_values(param, slider_binding.read())
+            holder.content = field
+        else:
+            holder.content = slider_binding.row
+        read()
+        page.update()
+
+    switch.on_change = on_toggle
+    field.on_change = lambda e: read()
+    row = ft.Row(vertical_alignment=ft.CrossAxisAlignment.CENTER, controls=[holder, switch])
+    return ControlBinding(row=row, read=read)
+
+
+def tuple_control(name, label, param, value, values):
+    """A fixed-size tuple: one small text field per element."""
+    fields = [
+        ft.TextField(value=f"{element:g}", width=90, text_align=ft.TextAlign.RIGHT, text_style=MONO)
+        for element in tuple(value)
+    ]
+
+    def read():
+        previous = tuple(values.get(name, param.default))
+        parsed = tuple(
+            parse_scalar(param, field.value, fallback=element)
+            for field, element in zip(fields, previous)
+        )
+        values[name] = parsed
+        return parsed
+
+    for field in fields:
+        field.on_change = lambda e: read()
+    row = ft.Row(
+        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        controls=[ft.Text(label, width=120, style=MONO), *fields],
+    )
+    return ControlBinding(row=row, read=read)
+
+
+def slider_row(label, slider, readout):
+    """A labelled slider with its live readout to the right."""
+    return ft.Row(
+        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        controls=[
+            ft.Text(label, width=120, style=MONO),
+            ft.Container(slider, expand=True),
+            readout,
+        ],
+    )
+
+
+def cast(param, value):
+    """
+    Cast a slider value or one token of user text to the param's kind, rounding
+    to the nearest int; raises on unparseable text.
+
+    A tuple param's elements are floats, so they take the non-int branch.
+    """
+    return int(round(float(value))) if param.kind == "int" else float(value)
+
+
+def format_scalar(param, value):
+    """Display form of one value: thousands-grouped ints, compact floats."""
+    return f"{int(value):,}" if param.kind == "int" else f"{float(value):g}"
+
+
+def format_values(param, value):
+    """
+    Display form of a committed value or scan list for a comma field.
+
+    Ints are ungrouped here, unlike format_scalar: a thousands separator inside
+    a comma-separated list would parse back as two values.
+    """
+    entries = value if isinstance(value, list) else [value]
+    return ", ".join(f"{int(v):d}" if param.kind == "int" else f"{float(v):g}" for v in entries)
+
+
+def parse_scalar(param, text, fallback):
+    """Parse one value of the param's kind, keeping fallback on bad input."""
+    try:
+        return cast(param, text)
+    except (TypeError, ValueError):
+        return fallback
+
+
+def parse_values(param, text, fallback):
+    """
+    Parse a comma-separated scan entry.
+
+    A single valid value returns a scalar (a one-point scan is just a run);
+    several return a list; no valid values return the fallback.
+    """
+    parsed = []
+    for token in str(text).split(","):
+        token = token.strip()
+        if not token:
+            continue
+        try:
+            parsed.append(cast(param, token))
+        except ValueError:
+            return fallback
+    if not parsed:
+        return fallback
+    return parsed[0] if len(parsed) == 1 else parsed

labforge/figures.py

@@ -0,0 +1,92 @@
+"""
+Serialize the author's matplotlib figures to base64 PNGs, plus an optional
+house style.
+"""
+
+import base64
+import io
+
+import matplotlib
+
+matplotlib.use("Agg")  # render to a buffer; no GUI backend on the UI thread
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+
+from . import theme
+
+RENDER_DPI = 150
+
+
+def palette():
+    """
+    The active Theme, for an author colouring their own figure; its data /
+    model / highlight / ink / grid fields are the plot palette. Read at call
+    time rather than bound at import, so a figure drawn with palette().data
+    follows whichever theme open(theme=...) selected.
+    """
+    return theme.active()
+
+
+def is_figure(value):
+    """True for a matplotlib Figure or a (fig, ...) tuple, the two viz returns."""
+    if isinstance(value, tuple):
+        return bool(value) and isinstance(value[0], Figure)
+    return isinstance(value, Figure)
+
+
+def unpack_figure(value):
+    """Extract the Figure from a viz return: a bare Figure or a (fig, ...) tuple."""
+    if not is_figure(value):
+        raise TypeError(
+            f"Expected a matplotlib Figure or a (fig, ax) tuple, got {type(value).__name__}."
+        )
+    return value[0] if isinstance(value, tuple) else value
+
+
+def figure_to_base64(fig):
+    """
+    Serialize a matplotlib figure to a base64 PNG and close it, so repeated
+    renders never leak pyplot state.
+    """
+    buffer = io.BytesIO()
+    # transparent=True clears the figure and axes patches so the app surface
+    # shows through; the pale ink still reads on the dark theme.
+    fig.savefig(buffer, format="png", dpi=RENDER_DPI, bbox_inches="tight", transparent=True)
+    plt.close(fig)
+    return base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+def style(fig, ax):
+    """
+    Apply the optional house figure treatment in place.
+
+    Open top/right spines, a light dotted grid behind the data, muted ink and
+    compact type, and a frameless legend — so an opted-in figure reads as part
+    of the app rather than a stock matplotlib window.
+
+    Parameters
+    ----------
+    fig: Figure
+        The figure (accepted for signature symmetry with viz returns).
+    ax: Axes
+        The axes to restyle, already populated by the caller.
+    """
+    colors = theme.active()
+    for side in ("top", "right"):
+        ax.spines[side].set_visible(False)
+    for side in ("left", "bottom"):
+        ax.spines[side].set_color(colors.grid)
+    ax.grid(True, axis="y", color=colors.grid, alpha=0.35, linewidth=0.6, linestyle=":")
+    ax.set_axisbelow(True)
+    ax.tick_params(colors=colors.ink, labelsize=9)
+    ax.title.set_color(colors.ink)
+    ax.title.set_fontsize(11)
+    for label in (ax.xaxis.label, ax.yaxis.label):
+        label.set_color(colors.ink)
+        label.set_fontsize(10)
+    legend = ax.get_legend()
+    if legend is not None:
+        legend.set_frame_on(False)
+        for text in legend.get_texts():
+            text.set_color(colors.ink)
+            text.set_fontsize(9)

labforge/lab.py

@@ -0,0 +1,165 @@
+"""
+Lab: register a worker, visualizations, analyses and theory, then open the app.
+"""
+
+import os
+
+from .param import normalize_spec
+from .registry import AnalysisSpec, VizSpec, WorkerSpec
+from .theme import DEFAULT as DEFAULT_THEME
+
+
+class Lab:
+    """
+    A four-page scientific desktop app assembled from plain functions.
+
+    Every registration is validated on the spot — spec keys checked against the
+    function signature, defaults resolved — so a malformed app fails at
+    assembly rather than mid-navigation.
+
+    Parameters
+    ----------
+    title: str
+        App name shown in the top bar.
+    page_title: str
+        Window title; defaults to title.
+    icon: str
+        A Flet icon constant for the top-bar app mark; a volume mark by default.
+    """
+
+    def __init__(self, title, page_title=None, icon=""):
+        self.title = title
+        self.page_title = page_title or title
+        self.icon = icon
+        self.theory_source = None
+        self.worker = None
+        self.vizzes = []
+        self.analyses = []
+
+    def set_theory(self, source):
+        """
+        Register the Theory page content.
+
+        Parameters
+        ----------
+        source: str or Path
+            Path to a markdown file, or raw markdown. Displayed equations in
+            $$...$$ blocks render as LaTeX images.
+        """
+        source = os.fspath(source)
+        if os.path.isfile(source):
+            with open(source, encoding="utf-8") as handle:
+                source = handle.read()
+        self.theory_source = source
+
+    def add_worker(self, func, spec=None):
+        """
+        Register the data-producing function.
+
+        Parameters
+        ----------
+        func: callable
+            Called with one scalar per kwarg; a scan calls it once per grid
+            point. Its return is the data handed to viz and analysis functions.
+        spec: dict
+            {kwarg: Param or shorthand str}; unspecced kwargs are inferred from
+            their signature defaults.
+        """
+        # One worker per Lab: a second would need a picker and a workspace stash
+        # to switch between their results, which is a larger design than this.
+        if self.worker is not None:
+            raise ValueError(
+                "labforge supports one worker per Lab; already registered "
+                f"{self.worker.func.__name__}."
+            )
+        self.worker = WorkerSpec(func=func, params=normalize_spec(func, spec))
+
+    def add_viz(self, func, title, desc="", spec=None):
+        """
+        Register a visualization tab.
+
+        Parameters
+        ----------
+        func: callable
+            func(data, **kwargs) returning a matplotlib Figure or (fig, ax).
+            data is the worker's bare return, or a ScanResult after a scan.
+        title: str
+            Tab label.
+        desc: str
+            Short markdown note shown above the controls.
+        spec: dict
+            {kwarg: Param or shorthand str} for the kwargs after data.
+        """
+        params = normalize_spec(func, spec, skip_first=True, allow_scan=False)
+        self.vizzes.append(VizSpec(func=func, title=title, desc=desc, params=params))
+
+    def add_analysis(self, func, title, desc="", spec=None):
+        """
+        Register an analysis tab.
+
+        Parameters
+        ----------
+        func: callable
+            func(data, **kwargs) returning a dict (two-column table), a list of
+            dicts (table), a string (markdown), or a matplotlib figure.
+        title: str
+            Tab label.
+        desc: str
+            Short markdown note shown above the controls.
+        spec: dict
+            {kwarg: Param or shorthand str} for the kwargs after data.
+        """
+        params = normalize_spec(func, spec, skip_first=True, allow_scan=False)
+        self.analyses.append(AnalysisSpec(func=func, title=title, desc=desc, params=params))
+
+    def build_main(self, layout="pages", theme=DEFAULT_THEME):
+        """
+        Return the Flet main(page) entry point; also the headless test seam.
+
+        Parameters
+        ----------
+        layout: str
+            "pages" or "scroll", as in open().
+        theme: str
+            A key of labforge.themes(), as in open().
+
+        Returns
+        -------
+        A main(page) callable.
+        """
+        if self.worker is None:
+            raise ValueError("Register a worker with add_worker before opening the lab.")
+        # Imported here, not at module scope, so registration and validation
+        # never pay for Flet's UI layer.
+        from .shell import build_main
+
+        return build_main(self, layout=layout, theme=theme)
+
+    def open(self, view="app", layout="pages", port=0, theme=DEFAULT_THEME):
+        """
+        Launch the app.
+
+        Parameters
+        ----------
+        view: str
+            "app" opens a native desktop window; "browser" serves the app and
+            opens it in the default web browser — handy for iterating, since a
+            served app is reachable from any browser on a stable URL.
+        layout: str
+            "pages" navigates the four pages with a rail; "scroll" shows the
+            whole lab as one continuous scrolling page.
+        port: int
+            Port for the "browser" view; 0 lets the OS pick a free one. With a
+            fixed port the app stays at http://localhost:<port> across relaunches.
+        theme: str
+            The colour scheme: any key of labforge.themes(), which lists each
+            with a one-line note. Sets the chrome, the plot palette and the
+            equation ink together, so a figure drawn with labforge.palette()
+            follows it.
+        """
+        import flet as ft
+
+        views = {"app": ft.AppView.FLET_APP, "browser": ft.AppView.WEB_BROWSER}
+        if view not in views:
+            raise ValueError(f"view must be one of {sorted(views)}, got {view!r}.")
+        ft.run(self.build_main(layout=layout, theme=theme), view=views[view], port=port)

labforge/mathtext.py

@@ -0,0 +1,140 @@
+"""
+Render LaTeX math to a base64 PNG: system LaTeX when present, matplotlib's
+mathtext otherwise.
+
+Flet has no equation widget, and an image renders identically on every platform.
+"""
+
+import base64
+import io
+import os
+import shutil
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless: render to a buffer, never open a window
+import matplotlib.pyplot as plt
+
+from . import theme
+
+# Rendered at 2x, displayed at 1x, so equations stay crisp on retina screens.
+RENDER_DPI = 220
+DISPLAY_SCALE = 0.5
+
+# amssymb supplies \mathbb; amsmath the spacing/alignment macros the prose uses;
+# eulervm sets the math font to Euler (Zapf), the app's mathematical voice.
+LATEX_PREAMBLE = r"\usepackage{amsmath}\usepackage{amssymb}\usepackage[euler-digits]{eulervm}"
+
+# MacTeX installs its binaries here, but a GUI-launched process may not inherit it
+# on PATH — add it so both the availability probe and matplotlib's subprocess find
+# latex/dvipng.
+TEX_BIN = "/Library/TeX/texbin"
+if os.path.isdir(TEX_BIN) and TEX_BIN not in os.environ.get("PATH", "").split(os.pathsep):
+    os.environ["PATH"] = TEX_BIN + os.pathsep + os.environ.get("PATH", "")
+
+
+def latex_available():
+    """True when a system LaTeX toolchain (latex + dvipng) is on PATH."""
+    return bool(shutil.which("latex") and shutil.which("dvipng"))
+
+
+# Probed once at import. A render failure later (missing package, unsupported
+# glyph) latches this off for the session, since that failure mode is systemic and
+# retrying it pays a slow subprocess timeout on every equation.
+USE_LATEX = latex_available()
+
+
+def render_png(latex, fontsize, usetex):
+    """
+    Render a LaTeX math string to a base64 PNG and its display size.
+
+    Parameters
+    ----------
+    latex: str
+        Math content without surrounding dollar signs, e.g. r"f(x)=\\lambda".
+    fontsize: int
+        Point size of the rendered equation.
+    usetex: bool
+        Compile with the system LaTeX toolchain when True, else use mathtext.
+        The usetex path accepts the full LaTeX command set (\\mathbb, \\mathcal,
+        alignment environments) that mathtext only partly supports, and sets the
+        math font to Euler; mathtext's cost is a narrower vocabulary and
+        Computer-Modern glyphs.
+
+    Returns
+    -------
+    Tuple of (base64 src, width in inches, height in inches).
+    """
+    # rc_context keeps usetex local to this figure, so it never touches an
+    # author's own plots.
+    rc = {"text.usetex": usetex}
+    if usetex:
+        rc["text.latex.preamble"] = LATEX_PREAMBLE
+    with plt.rc_context(rc):
+        fig = plt.figure()
+        # Displayed equations get display style — full-size fractions, sum
+        # limits above and below. Only usetex knows \displaystyle; the mathtext
+        # fallback keeps text style, one more of its accepted costs.
+        body = f"\\displaystyle {latex}" if usetex else latex
+        # Ink follows the active theme, so equations sit on the app surface the
+        # transparent PNG is composited onto rather than fighting it.
+        text = fig.text(0, 0, f"${body}$", fontsize=fontsize, color=theme.active().ink)
+
+        # Measure the drawn text so we can crop the canvas tightly around it.
+        fig.canvas.draw()
+        bbox = text.get_window_extent()
+        pad = fontsize * 0.35
+        width_in = (bbox.width + 2 * pad) / fig.dpi
+        height_in = (bbox.height + 2 * pad) / fig.dpi
+        fig.set_size_inches(width_in, height_in)
+        text.set_position((pad / bbox.width if bbox.width else 0.1, 0.5))
+        text.set_verticalalignment("center")
+
+        buffer = io.BytesIO()
+        fig.savefig(
+            buffer,
+            format="png",
+            dpi=RENDER_DPI,
+            transparent=True,
+            bbox_inches="tight",
+            pad_inches=0.08,
+        )
+        plt.close(fig)
+
+    src = base64.b64encode(buffer.getvalue()).decode("ascii")
+    return src, width_in, height_in
+
+
+def equation_image(latex, fontsize=18):
+    """
+    Render a LaTeX math string to a base64 PNG suitable for ft.Image.
+
+    Prefers the system LaTeX toolchain and falls back to mathtext when it is
+    absent or a render fails, so a page never blanks on an equation.
+
+    Parameters
+    ----------
+    latex: str
+        Math content without surrounding dollar signs, e.g. r"f(x)=\\lambda".
+    fontsize: int
+        Point size of the rendered equation.
+
+    Returns
+    -------
+    dict with base64 src plus display width and height in logical pixels.
+    """
+    global USE_LATEX
+    if USE_LATEX:
+        try:
+            src, width_in, height_in = render_png(latex, fontsize, usetex=True)
+        except Exception:
+            USE_LATEX = False
+            src, width_in, height_in = render_png(latex, fontsize, usetex=False)
+    else:
+        src, width_in, height_in = render_png(latex, fontsize, usetex=False)
+
+    return {
+        "src": src,
+        "width": width_in * RENDER_DPI * DISPLAY_SCALE,
+        "height": height_in * RENDER_DPI * DISPLAY_SCALE,
+    }

labforge/pages/__init__.py

@@ -0,0 +1,6 @@
+"""
+The stock page builders the shell navigates between.
+
+Each exposes build(state, page) and is re-invoked on every visit
+(rebuild-on-navigate), so a fresh build always reflects the latest LabState.
+"""