labforge 0.1.0__py3-none-any.whl

labforge/scan.py

@@ -0,0 +1,75 @@
+"""
+The scan engine: run the worker once, or over a cartesian grid of scan axes.
+
+Pure Python, no Flet — unit-testable without a UI.
+"""
+
+import itertools
+from dataclasses import dataclass
+
+
+@dataclass
+class ScanResult:
+    """
+    The collected output of a parameter scan.
+
+    A list of (params, result) records rather than a tuple-keyed dict: records
+    are self-describing (each carries its full kwarg dict), preserve cartesian
+    order, and avoid float-equality lookups.
+
+    Parameters
+    ----------
+    keys: list
+        The scanned kwarg names, in control order.
+    points: list
+        (params dict, worker return) tuples, in cartesian-product order.
+    """
+
+    keys: list
+    points: list
+
+    def __iter__(self):
+        return iter(self.points)
+
+    def __len__(self):
+        return len(self.points)
+
+    def values(self):
+        """The worker returns alone, in cartesian-product order."""
+        return [value for _, value in self.points]
+
+    def axis(self, key):
+        """The distinct values one scanned kwarg took, in entry order."""
+        return list(dict.fromkeys(params[key] for params, _ in self.points))
+
+
+def run_worker(func, values):
+    """
+    Call the worker once, or over the cartesian grid of its scan axes.
+
+    The worker always receives scalars: an axis is expanded into one call per
+    grid point, never passed through as a list. Viz and analysis functions tell
+    the two cases apart with isinstance(data, ScanResult).
+
+    Parameters
+    ----------
+    func: callable
+        The registered worker.
+    values: dict
+        Parsed control values; list-valued entries are scan axes.
+
+    Returns
+    -------
+    The worker's bare return for a pure-scalar call, or a ScanResult when any
+    axis is a list.
+    """
+    axes = {key: value for key, value in values.items() if isinstance(value, list)}
+    if not axes:
+        return func(**values)
+
+    fixed = {key: value for key, value in values.items() if key not in axes}
+    points = []
+    for combo in itertools.product(*axes.values()):
+        params = dict(fixed, **dict(zip(axes.keys(), combo)))
+        points.append((params, func(**params)))
+    return ScanResult(keys=list(axes.keys()), points=points)

labforge/shell.py

@@ -0,0 +1,220 @@
+"""
+The app chrome: top bar, navigation rail or scroll layout, and the single
+LabState every page shares.
+"""
+
+import flet as ft
+
+from . import theme as themes
+from . import ui
+from .pages import analysis, scroll, simulation, theory, visualization
+from .state import LabState
+
+PAGES = [
+    ("Theory", ft.Icons.MENU_BOOK, theory.build),
+    ("Simulation", ft.Icons.TERMINAL, simulation.build),
+    ("Visualization", ft.Icons.AUTO_GRAPH, visualization.build),
+    ("Analysis", ft.Icons.TROUBLESHOOT, analysis.build),
+]
+
+LAYOUTS = ("pages", "scroll")
+
+
+def color_scheme(theme):
+    """
+    Map a Theme onto the Flet ColorScheme slots the pages resolve through.
+
+    Pages never name a hex; they style themselves with ft.Colors tokens, so this
+    mapping is the only place the palette reaches the UI.
+    """
+    return ft.ColorScheme(
+        primary=theme.accent,
+        on_primary=theme.on_accent,
+        primary_container=theme.accent_dim,
+        on_primary_container=theme.on_accent_dim,
+        secondary=theme.accent,
+        on_secondary=theme.on_accent,
+        secondary_container=theme.accent_dim,
+        on_secondary_container=theme.on_accent_dim,
+        surface=theme.surface,
+        on_surface=theme.on_surface,
+        on_surface_variant=theme.on_surface_variant,
+        surface_container_lowest=theme.surface_lowest,
+        surface_container_low=theme.surface_low,
+        surface_container=theme.surface_container,
+        surface_container_high=theme.surface_high,
+        surface_container_highest=theme.surface_highest,
+        outline=theme.outline,
+        outline_variant=theme.outline_variant,
+        surface_tint=theme.accent,
+    )
+
+
+def build_main(lab, layout="pages", theme=themes.DEFAULT):
+    """
+    Return the Flet entry point — a main(page) callable — for a Lab.
+
+    Parameters
+    ----------
+    lab: Lab
+        The validated registrations and branding.
+    layout: str
+        "pages" for the rail-navigated four-page shell, "scroll" for one
+        continuous scrolling page.
+    theme: str
+        A key of theme.THEMES. Selected here, once, before the app serves —
+        figures and equations read it back through theme.active().
+
+    Returns
+    -------
+    A main(page) callable; also the headless seam the page-tree tests drive.
+    """
+    if layout not in LAYOUTS:
+        raise ValueError(f"layout must be one of {sorted(LAYOUTS)}, got {layout!r}.")
+
+    palette = themes.use(theme)
+    scheme = color_scheme(palette)
+
+    # Flet calls main(page) once per connection, so every browser tab that opens
+    # the served app gets its own LabState. Nothing may be cached out here
+    # except immutable config.
+    def main(page):
+        page.title = lab.page_title
+        # The mode matches the palette so widget defaults the scheme does not
+        # name (shadows, ripples, error tones) derive with the right brightness.
+        page.theme_mode = ft.ThemeMode.DARK if palette.mode == "dark" else ft.ThemeMode.LIGHT
+        # The seed fills the scheme slots color_scheme leaves unset; the same
+        # Theme is set on both slots so the explicit surfaces win regardless of
+        # which one Flet consults for the mode.
+        page_theme = ft.Theme(
+            color_scheme_seed=palette.accent, color_scheme=scheme, font_family=ui.FONT_BODY
+        )
+        page.theme = page_theme
+        page.dark_theme = page_theme
+        page.window.width = 1120
+        page.window.height = 840
+        page.window.min_width = 900
+        page.window.min_height = 640
+
+        # The one state object every page reads from and writes to.
+        state = LabState(lab)
+
+        # App mark: the lab's icon (a volume mark by default) on a sharp accent tile.
+        app_mark = ft.Container(
+            width=30,
+            height=30,
+            border_radius=2,
+            bgcolor=ft.Colors.PRIMARY,
+            alignment=ft.Alignment.CENTER,
+            content=ft.Icon(lab.icon or ft.Icons.VIEW_IN_AR, size=18, color=ft.Colors.ON_PRIMARY),
+        )
+
+        # Thin header strip: mark and tracked mono-caps title on the left, a
+        # factual mono readout (the registered worker) on the right.
+        top_bar = ft.Container(
+            padding=ft.Padding.symmetric(horizontal=20, vertical=10),
+            bgcolor=ft.Colors.SURFACE_CONTAINER_LOWEST,
+            content=ft.Row(
+                alignment=ft.MainAxisAlignment.SPACE_BETWEEN,
+                vertical_alignment=ft.CrossAxisAlignment.CENTER,
+                controls=[
+                    ft.Row(
+                        spacing=12,
+                        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+                        controls=[
+                            app_mark,
+                            ft.Text(
+                                lab.title.upper(),
+                                style=ft.TextStyle(
+                                    size=14,
+                                    weight=ft.FontWeight.W_700,
+                                    letter_spacing=3,
+                                    font_family=ui.FONT_MONO,
+                                ),
+                            ),
+                        ],
+                    ),
+                    ft.Text(
+                        f"WORKER · {lab.worker.func.__name__.upper()}",
+                        style=ft.TextStyle(
+                            size=11,
+                            letter_spacing=2,
+                            font_family=ui.FONT_MONO,
+                            color=ft.Colors.ON_SURFACE_VARIANT,
+                        ),
+                    ),
+                ],
+            ),
+        )
+
+        if layout == "scroll":
+            # One continuous page under the top bar; no rail, no navigation.
+            body = ft.Container(expand=True, padding=24, content=scroll.build(state, page))
+        else:
+            # Right-hand pane; its single child is swapped on navigation.
+            content = ft.Container(expand=True, padding=24)
+
+            def show_page(index):
+                # Rebuild-on-navigate: build fresh so the page re-reads LabState.
+                content.content = PAGES[index][2](state, page)
+
+            def on_nav_change(e):
+                show_page(e.control.selected_index)
+                page.update()
+
+            # Spec-sheet rail: numbered mono-caps labels, a squared indicator.
+            rail = ft.NavigationRail(
+                selected_index=0,
+                label_type=ft.NavigationRailLabelType.ALL,
+                min_width=100,
+                bgcolor=ft.Colors.SURFACE_CONTAINER_LOWEST,
+                indicator_color=ft.Colors.PRIMARY_CONTAINER,
+                indicator_shape=ft.RoundedRectangleBorder(radius=2),
+                selected_label_text_style=ft.TextStyle(
+                    size=11,
+                    weight=ft.FontWeight.W_700,
+                    letter_spacing=1.5,
+                    font_family=ui.FONT_MONO,
+                    color=ft.Colors.PRIMARY,
+                ),
+                unselected_label_text_style=ft.TextStyle(
+                    size=11,
+                    letter_spacing=1.5,
+                    font_family=ui.FONT_MONO,
+                    color=ft.Colors.ON_SURFACE_VARIANT,
+                ),
+                on_change=on_nav_change,
+                destinations=[
+                    ft.NavigationRailDestination(
+                        icon=icon, label=f"{index + 1:02d} {label.upper()}"
+                    )
+                    for index, (label, icon, _) in enumerate(PAGES)
+                ],
+            )
+
+            # Render the first page before mounting, so no handler fires against
+            # an unattached tree.
+            show_page(0)
+
+            body = ft.Row(
+                expand=True,
+                controls=[
+                    rail,
+                    ft.VerticalDivider(width=1, color=ft.Colors.OUTLINE_VARIANT),
+                    content,
+                ],
+            )
+
+        page.add(
+            ft.Column(
+                expand=True,
+                spacing=0,
+                controls=[
+                    top_bar,
+                    ft.Divider(height=1, color=ft.Colors.OUTLINE_VARIANT),
+                    body,
+                ],
+            )
+        )
+
+    return main

labforge/state.py

@@ -0,0 +1,74 @@
+"""
+LabState: the mutable workspace every page of a running app shares.
+
+Pages are rebuilt fresh on each navigation and the state has no observers, so
+anything that must survive a rebuild lives here.
+"""
+
+import time
+from dataclasses import dataclass, field
+
+from .scan import ScanResult, run_worker
+
+
+@dataclass
+class LabState:
+    """
+    The mutable workspace of a running Lab.
+
+    Parameters
+    ----------
+    lab: Lab
+        The registrations; read-only from pages.
+    worker_values: dict
+        Current parsed control values; list-valued entries are scan axes.
+    data: object
+        The last run's output — the worker's bare return, or a ScanResult.
+    n_points: int
+        Grid size of the last run (1 for a scalar run, 0 before any run).
+    run_summary: str
+        Status line shown on the Simulation page.
+    viz_values: dict
+        {viz title: {kwarg: value}}, persisted across page rebuilds.
+    analysis_values: dict
+        {analysis title: {kwarg: value}}, persisted across page rebuilds.
+    """
+
+    lab: object
+    worker_values: dict = None
+    data: object = None
+    n_points: int = 0
+    run_summary: str = ""
+    viz_values: dict = field(default_factory=dict)
+    analysis_values: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        # Seed every control value from its normalized Param default.
+        if self.worker_values is None:
+            self.worker_values = defaults(self.lab.worker.params)
+        for entry in self.lab.vizzes:
+            self.viz_values.setdefault(entry.title, defaults(entry.params))
+        for entry in self.lab.analyses:
+            self.analysis_values.setdefault(entry.title, defaults(entry.params))
+
+    def has_data(self):
+        """True once the worker has produced data; gates Viz and Analysis."""
+        return self.n_points > 0
+
+    def run(self):
+        """Run the worker over the current values and record a telemetry line."""
+        start = time.perf_counter()
+        self.data = run_worker(self.lab.worker.func, self.worker_values)
+        self.n_points = len(self.data) if isinstance(self.data, ScanResult) else 1
+        elapsed = time.perf_counter() - start
+        # Report the grid the author actually asked for, not just the point count.
+        axes = sum(1 for value in self.worker_values.values() if isinstance(value, list))
+        grid = f"{self.n_points} {'POINT' if self.n_points == 1 else 'POINTS'}"
+        if axes:
+            grid += f" · {axes} {'AXIS' if axes == 1 else 'AXES'}"
+        self.run_summary = f"RUN COMPLETE · {grid} · {elapsed:.2f} s"
+
+
+def defaults(params):
+    """Initial control values for a normalized {name: Param} spec."""
+    return {name: param.default for name, param in params.items()}

labforge/theme.py

@@ -0,0 +1,323 @@
+"""
+The colour table — chrome, plot palette and equation ink — and the one
+process-wide selection of it.
+
+Holding all three in one frozen value is what keeps them from drifting apart.
+Pure hexes, no Flet import: shell.py owns the mapping onto ColorScheme slots, so
+figures.py and mathtext.py read the palette without pulling in the UI layer.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Theme:
+    """
+    Every colour the app draws, chrome and plots together.
+
+    Parameters
+    ----------
+    name: str
+        The key open(theme=...) selects this theme by.
+    note: str
+        One-line description, shown by names().
+    mode: str
+        "dark" or "light"; drives the Flet ThemeMode so widget defaults the
+        scheme does not name (shadows, ripples, error tones) match the surfaces.
+    accent: str
+        The single electric colour reserved for interactive and live things.
+    on_accent: str
+        Ink drawn on top of accent fills; carries the accent's contrast burden.
+    accent_dim: str
+        Muted accent fill for selected-but-not-active chrome (the rail indicator).
+    on_accent_dim: str
+        Ink on accent_dim.
+    surface: str
+        The page background.
+    surface_lowest: str
+        Recessed chrome — the top bar and rail.
+    surface_low: str
+        The lowest raised container step.
+    surface_container: str
+        The standard card fill.
+    surface_high: str
+        A raised card step.
+    surface_highest: str
+        The most raised step; input fills.
+    on_surface: str
+        Body ink.
+    on_surface_variant: str
+        Secondary ink — labels, readouts, anything factual but not primary.
+    outline: str
+        Borders that must read as a boundary.
+    outline_variant: str
+        Hairline dividers that must not.
+    data: str
+        Plot colour for the worker's data — matches accent, so a figure reads as
+        part of the app.
+    model: str
+        Plot colour for a model or comparison curve; contrasts with data.
+    highlight: str
+        Third plot colour, for an emphasised subset.
+    ink: str
+        Plot and equation ink. Sits on a transparent PNG over surface, so it
+        tracks on_surface rather than being pure white.
+    grid: str
+        Plot grid and spines.
+    """
+
+    name: str
+    note: str
+    mode: str
+    accent: str
+    on_accent: str
+    accent_dim: str
+    on_accent_dim: str
+    surface: str
+    surface_lowest: str
+    surface_low: str
+    surface_container: str
+    surface_high: str
+    surface_highest: str
+    on_surface: str
+    on_surface_variant: str
+    outline: str
+    outline_variant: str
+    data: str
+    model: str
+    highlight: str
+    ink: str
+    grid: str
+
+
+THEMES = {
+    "instrument": Theme(
+        name="instrument",
+        note="Near-black teal-tinted surfaces, one electric accent.",
+        mode="dark",
+        accent="#2BE4C8",
+        on_accent="#04211C",
+        accent_dim="#123B33",
+        on_accent_dim="#7FEFD9",
+        surface="#0B0F10",
+        surface_lowest="#080C0D",
+        surface_low="#11181A",
+        surface_container="#141C1E",
+        surface_high="#182123",
+        surface_highest="#1C2628",
+        on_surface="#E4EBEA",
+        on_surface_variant="#8CA0A0",
+        outline="#3C4C4E",
+        outline_variant="#233032",
+        data="#2BE4C8",
+        model="#FF4D9E",
+        highlight="#7FEFD9",
+        ink="#D9E2E0",
+        grid="#3A4649",
+    ),
+    "neon_violet": Theme(
+        name="neon_violet",
+        mode="dark",
+        note="Violet chrome with hot-pink data on black.",
+        accent="#9929EA",
+        on_accent="#FFFFFF",
+        accent_dim="#2E1147",
+        on_accent_dim="#D9A6FF",
+        surface="#000000",
+        surface_lowest="#0A0410",
+        surface_low="#120818",
+        surface_container="#170A22",
+        surface_high="#1E0E2C",
+        surface_highest="#251236",
+        on_surface="#F3EAFB",
+        on_surface_variant="#A98BC4",
+        outline="#3B1B57",
+        outline_variant="#26113A",
+        data="#FF5FCF",
+        model="#FAEB92",
+        highlight="#9929EA",
+        ink="#F3EAFB",
+        grid="#3B1B57",
+    ),
+    "neon_gold": Theme(
+        name="neon_gold",
+        mode="dark",
+        note="The violet palette with pale gold as the accent instead.",
+        accent="#FAEB92",
+        on_accent="#1A0B26",
+        accent_dim="#3E3418",
+        on_accent_dim="#FAEB92",
+        surface="#000000",
+        surface_lowest="#0C0610",
+        surface_low="#150823",
+        surface_container="#1A0B26",
+        surface_high="#221030",
+        surface_highest="#29143A",
+        on_surface="#F6EEFC",
+        on_surface_variant="#AE90C8",
+        outline="#43205F",
+        outline_variant="#2B1440",
+        data="#FF5FCF",
+        model="#9929EA",
+        highlight="#FAEB92",
+        ink="#F6EEFC",
+        grid="#43205F",
+    ),
+    "retro_green": Theme(
+        name="retro_green",
+        mode="dark",
+        note="Matrix mood with a calmer green and a legible olive card.",
+        accent="#08CB00",
+        on_accent="#00230A",
+        accent_dim="#12400A",
+        on_accent_dim="#7CFF77",
+        surface="#000000",
+        surface_lowest="#050805",
+        surface_low="#1B2A00",
+        surface_container="#253900",
+        surface_high="#2E4600",
+        surface_highest="#375300",
+        on_surface="#EEEEEE",
+        on_surface_variant="#8FA07A",
+        outline="#3A5410",
+        outline_variant="#223300",
+        data="#08CB00",
+        model="#EEEEEE",
+        highlight="#7CFF77",
+        ink="#EEEEEE",
+        grid="#3A5410",
+    ),
+    "paper": Theme(
+        name="paper",
+        note="Warm paper surfaces, graphite ink and a vermilion accent.",
+        mode="light",
+        accent="#C14B2E",
+        on_accent="#FFF6F1",
+        accent_dim="#F2D9CE",
+        on_accent_dim="#8A2F1B",
+        surface="#FAF6EF",
+        surface_lowest="#F1EAD9",
+        surface_low="#FFFFFF",
+        surface_container="#FFFDF8",
+        surface_high="#FFFFFF",
+        surface_highest="#FFFFFF",
+        on_surface="#33302A",
+        on_surface_variant="#7A7264",
+        outline="#C9BFA9",
+        outline_variant="#E5DECC",
+        data="#C14B2E",
+        model="#2E6F8E",
+        highlight="#E0A458",
+        ink="#33302A",
+        grid="#C9BFA9",
+    ),
+    "mint": Theme(
+        name="mint",
+        note="Light mint greens on white, colorhunt's fresh-green family.",
+        mode="light",
+        accent="#3E8E5A",
+        on_accent="#F2FBF4",
+        accent_dim="#D8F0DC",
+        on_accent_dim="#2C6E44",
+        surface="#F4FAEF",
+        surface_lowest="#E4F3DA",
+        surface_low="#FFFFFF",
+        surface_container="#FBFEF8",
+        surface_high="#FFFFFF",
+        surface_highest="#FFFFFF",
+        on_surface="#24312A",
+        on_surface_variant="#6D8072",
+        outline="#B9CDB9",
+        outline_variant="#DCE9D8",
+        data="#3E8E5A",
+        model="#B85B9E",
+        highlight="#7FBF6C",
+        ink="#24312A",
+        grid="#B9CDB9",
+    ),
+    "glacier": Theme(
+        name="glacier",
+        note="Pale glacier blues with a deep slate accent.",
+        mode="light",
+        accent="#4A628A",
+        on_accent="#F2F7FF",
+        accent_dim="#D5E4EE",
+        on_accent_dim="#35577D",
+        surface="#F2F8FA",
+        surface_lowest="#E0EEF2",
+        surface_low="#FFFFFF",
+        surface_container="#FAFDFE",
+        surface_high="#FFFFFF",
+        surface_highest="#FFFFFF",
+        on_surface="#22303B",
+        on_surface_variant="#64798A",
+        outline="#B4C8D4",
+        outline_variant="#DCE8EE",
+        data="#3D7EA6",
+        model="#C96A4A",
+        highlight="#4A628A",
+        ink="#22303B",
+        grid="#B4C8D4",
+    ),
+    "lavender": Theme(
+        name="lavender",
+        note="Soft lavender neutrals with a deep violet accent.",
+        mode="light",
+        accent="#7C6BD6",
+        on_accent="#F8F6FF",
+        accent_dim="#E3DBF7",
+        on_accent_dim="#5A4BB0",
+        surface="#F7F4FC",
+        surface_lowest="#EDE6F7",
+        surface_low="#FFFFFF",
+        surface_container="#FCFAFF",
+        surface_high="#FFFFFF",
+        surface_highest="#FFFFFF",
+        on_surface="#2C2838",
+        on_surface_variant="#756E88",
+        outline="#C4BBDA",
+        outline_variant="#E4DEF1",
+        data="#7C6BD6",
+        model="#D66B8F",
+        highlight="#A594F9",
+        ink="#2C2838",
+        grid="#C4BBDA",
+    ),
+}
+
+DEFAULT = "paper"
+
+# The process-wide selection, rebound only by use() before the app serves. This
+# is the one piece of module state the per-session rule tolerates: Flet calls
+# main(page) per browser connection, but every session resolves the same theme,
+# so it is config rather than shared mutable state.
+ACTIVE = THEMES[DEFAULT]
+
+
+def names():
+    """The registered themes as {name: note}, in registration order."""
+    return {name: theme.note for name, theme in THEMES.items()}
+
+
+def use(name):
+    """
+    Select the process-wide theme by name and return it.
+
+    Called once from shell.build_main before the app serves; see ACTIVE on why
+    process-wide state is safe here.
+    """
+    global ACTIVE
+    if name not in THEMES:
+        raise ValueError(f"theme must be one of {sorted(THEMES)}, got {name!r}.")
+    ACTIVE = THEMES[name]
+    return ACTIVE
+
+
+def active():
+    """
+    The active Theme: the palette figures and equations render with.
+
+    Read at draw time, never bound at import, so a figure follows whichever
+    theme open(theme=...) selected.
+    """
+    return ACTIVE