logqbit 0.0.1__py3-none-any.whl

logqbit/assets/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="5" refY="5" markerWidth="3" markerHeight="3"
+      orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#2DB84D" />
+    </marker>
+  </defs>
+  <g stroke="#2DB84D" stroke-width="28" stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <path d="M 96 432 L 96 96" />
+    <path d="M 96 432 L 416 432" />
+  </g>
+  <polyline points="136,360 220,220 300,300 396,168" fill="none" stroke="#2DB84D" stroke-width="32"
+    stroke-linecap="round" stroke-linejoin="round" marker-end="url(#arrow)" />
+  <circle cx="300" cy="360" r="20" fill="#2DB84D" />
+</svg>

logqbit/constants.py

@@ -0,0 +1,4 @@
+HEAD_LENGTH = 4  # Allows 4,294,967,295 bytes per message.
+CHUNK_SIZE = 100_000_000  # 100MB, too large will cause socket closed.
+
+LIVE_PLOTTER_PIPE_NAME = "logqbit-live-plotter"

logqbit/live_plotter.py

@@ -0,0 +1,665 @@
+from __future__ import annotations
+
+import pickle
+import sys
+import warnings
+from collections import deque
+from importlib.resources import files
+from typing import Any, Mapping, Sequence
+
+import pandas as pd
+import pyqtgraph as pg
+from PySide6.QtCore import QCoreApplication, QObject, Qt, Signal
+from PySide6.QtGui import QIcon, QPixmap
+from PySide6.QtNetwork import QLocalServer, QLocalSocket
+from PySide6.QtWidgets import (
+    QApplication,
+    QComboBox,
+    QHBoxLayout,
+    QLabel,
+    QMainWindow,
+    QPushButton,
+    QStatusBar,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .constants import HEAD_LENGTH, LIVE_PLOTTER_PIPE_NAME
+
+ACTIVE_COLOR = (255, 94, 0)
+INACTIVE_COLOR = (30, 144, 255, 120)
+DEFAULT_LINE_COUNT = 4
+
+
+def _safe_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class LivePlotterWindow(QMainWindow):
+    def __init__(
+        self,
+        line_count: int = DEFAULT_LINE_COUNT,
+        socket_name: str | None = LIVE_PLOTTER_PIPE_NAME,
+    ) -> None:
+        super().__init__()
+        pg.setConfigOptions(antialias=True)
+        self.setWindowTitle("LogQbit Live Plotter")
+        self.setWindowIcon(QIcon(QPixmap(str(files("logqbit") / "assets" / "icon.svg"))))
+
+        self.line_count = max(1, line_count)
+        self._active_index = 0
+        self._inactive_indices: deque[int] = deque(range(1, self.line_count))
+        self._last_stepper_values: tuple[Any, ...] | None = None
+        self._indeps: list[str] = []
+        self._stepper_keys: list[str] = []
+        self._dependent_keys: set[str] = set()
+        self._current_y_key: str | None = None
+        self._line_storage: list[list[dict[str, Any]]] = [
+            [] for _ in range(self.line_count)
+        ]
+        self._show_markers = False
+        self._marker_size = 4
+
+        self._active_symbol_brush = pg.mkBrush(ACTIVE_COLOR)
+        self._inactive_symbol_brush = pg.mkBrush(INACTIVE_COLOR)
+        self._active_symbol_pen = pg.mkPen(ACTIVE_COLOR)
+        self._inactive_symbol_pen = pg.mkPen(INACTIVE_COLOR)
+        self._active_pen = pg.mkPen(color=ACTIVE_COLOR, width=2)
+        self._inactive_pen = pg.mkPen(color=INACTIVE_COLOR, width=1)
+
+        self._build_ui()
+        self._configure_plot()
+
+        self._command_server: PlotterCommandServer | None = None
+        if socket_name:
+            self._command_server = PlotterCommandServer(self, socket_name)
+
+    # ------------------------------------------------------------------
+    # Public API exposed to IPC clients
+    # ------------------------------------------------------------------
+    def set_indeps(self, indeps: Sequence[str]) -> None:
+        indep_list = [str(item) for item in indeps if str(item)]
+        if not indep_list:
+            raise ValueError("'indeps' must contain at least one non-empty key")
+
+        self._indeps = indep_list
+        self._stepper_keys = indep_list[1:]
+        self._dependent_keys.clear()
+        self._current_y_key = None
+        self._last_stepper_values = None
+
+        self.plot_widget.setLabel("bottom", indep_list[0])
+
+        for storage in self._line_storage:
+            storage.clear()
+        self._active_index = 0
+        self._inactive_indices = deque(range(1, self.line_count))
+        for idx in range(self.line_count):
+            if idx == self._active_index:
+                self._set_active(idx)
+            else:
+                self._set_inactive(idx)
+
+        self._sync_y_selector()
+        self._set_status_message("")
+        self._refresh_all_lines()
+
+    def add(
+        self,
+        record: Mapping[str, Any] | pd.Series | None = None,
+        seg: pd.DataFrame | Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None,
+    ) -> None:
+        rows: list[Mapping[str, Any]] = []
+
+        if record is not None:
+            if isinstance(record, pd.Series):
+                rows.append(record.to_dict())
+            elif isinstance(record, Mapping):
+                rows.append(dict(record))
+            else:
+                raise TypeError("'record' must be a mapping or pandas Series")
+
+        if seg is not None:
+            if isinstance(seg, pd.DataFrame):
+                seg_df = seg
+            else:
+                try:
+                    seg_df = pd.DataFrame(seg)
+                except (TypeError, ValueError) as exc:  # pragma: no cover - defensive
+                    raise ValueError("'seg' must be convertible to a pandas DataFrame") from exc
+            rows.extend(seg_df.to_dict(orient="records"))
+
+        if not rows:
+            return
+
+        for row in rows:
+            self._ingest_row(dict(row))
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _build_ui(self) -> None:
+        central = QWidget(self)
+        root = QVBoxLayout()
+        root.setContentsMargins(0, 0, 0, 0)
+        root.setSpacing(0)
+
+        self.plot_widget = pg.PlotWidget(background="w", parent=self)
+        self.plot_widget.showGrid(x=True, y=True, alpha=0.25)
+        root.addWidget(self.plot_widget)
+
+        controls = QHBoxLayout()
+        controls.setContentsMargins(8, 4, 8, 4)
+        controls.setSpacing(8)
+
+        self.y_selector = QComboBox(self)
+        self.y_selector.currentTextChanged.connect(self._on_y_changed)
+        self.y_selector.setSizeAdjustPolicy(QComboBox.SizeAdjustPolicy.AdjustToContents)
+        controls.addWidget(self.y_selector)
+
+        self._status_bar = QStatusBar(self)
+        self._status_bar.setSizeGripEnabled(False)
+        self._status_bar.setContentsMargins(0, 0, 0, 0)
+        self._status_bar.setStyleSheet("QStatusBar::item { border: none; }")
+        self._status_label = QLabel("", self._status_bar)
+        self._status_label.setAlignment(Qt.AlignCenter)
+        self._status_bar.addWidget(self._status_label, 1)
+        controls.addWidget(self._status_bar, 1)
+
+        self.marker_button = QPushButton("Markers Off", self)
+        self.marker_button.setCheckable(True)
+        self.marker_button.setChecked(self._show_markers)
+        self.marker_button.toggled.connect(self._on_marker_toggled)
+        controls.addWidget(self.marker_button)
+
+        root.addLayout(controls)
+
+        central.setLayout(root)
+        self.setCentralWidget(central)
+
+        self._line_items: list[pg.PlotDataItem] = []
+        for idx in range(self.line_count):
+            pen = self._active_pen if idx == self._active_index else self._inactive_pen
+            item = self.plot_widget.plot([], [], pen=pen)
+            item.setZValue(10 if idx == self._active_index else 1)
+            self._line_items.append(item)
+
+    def _configure_plot(self) -> None:
+        self.plot_widget.setLabel("left", "")
+        self.plot_widget.setLabel("bottom", "")
+        self.plot_widget.addLegend()
+
+    def _on_marker_toggled(self, checked: bool) -> None:
+        self._show_markers = checked
+        self.marker_button.setText("Markers On" if checked else "Markers Off")
+        self._refresh_all_lines()
+
+    def _sync_y_selector(self) -> tuple[bool, str | None]:
+        previous = self._current_y_key
+        keys = sorted(self._dependent_keys)
+
+        self.y_selector.blockSignals(True)
+        self.y_selector.clear()
+        for key in keys:
+            self.y_selector.addItem(key)
+
+        changed = False
+        if not keys:
+            self._current_y_key = None
+            changed = previous is not None
+        else:
+            if previous in keys:
+                index = keys.index(previous)
+                self.y_selector.setCurrentIndex(index)
+                self._current_y_key = previous
+            else:
+                self.y_selector.setCurrentIndex(0)
+                self._current_y_key = keys[0]
+                changed = previous != self._current_y_key
+        self.y_selector.blockSignals(False)
+
+        if changed:
+            self._on_y_changed(self._current_y_key or "")
+        return changed, self._current_y_key
+
+    def _on_y_changed(self, text: str) -> None:
+        if not text:
+            self._current_y_key = None
+            self.plot_widget.setLabel("left", "")
+            for item in self._line_items:
+                item.setData([], [])
+            return
+
+        self._current_y_key = text
+        self.plot_widget.setLabel("left", text)
+        self._refresh_all_lines()
+
+    def _refresh_all_lines(self) -> None:
+        for idx in range(self.line_count):
+            self._refresh_line(idx)
+
+    def _refresh_line(self, index: int) -> None:
+        item = self._line_items[index]
+        if not self._current_y_key:
+            item.setData([], [])
+            item.setSymbol(None)
+            return
+
+        storage = self._line_storage[index]
+        if not storage:
+            item.setData([], [])
+            item.setSymbol(None)
+            return
+
+        x_values: list[float] = []
+        y_values: list[float] = []
+        for point in storage:
+            y_raw = point["values"].get(self._current_y_key)
+            y_value = _safe_float(y_raw)
+            if y_value is None:
+                continue
+            x_value = _safe_float(point["x"])
+            if x_value is None:
+                continue
+            x_values.append(x_value)
+            y_values.append(y_value)
+
+        item.setData(x_values, y_values)
+        if self._show_markers and x_values:
+            active = index == self._active_index
+            item.setSymbol("o")
+            item.setSymbolSize(self._marker_size)
+            item.setSymbolBrush(self._active_symbol_brush if active else self._inactive_symbol_brush)
+            item.setSymbolPen(self._active_symbol_pen if active else self._inactive_symbol_pen)
+        else:
+            item.setSymbol(None)
+
+    def _roll_lines(self) -> None:
+        if self.line_count == 1:
+            self._line_storage[0].clear()
+            self._refresh_line(0)
+            return
+
+        current = self._active_index
+        self._set_inactive(current)
+        self._inactive_indices.appendleft(current)
+
+        new_active = self._inactive_indices.pop()
+        self._active_index = new_active
+        self._line_storage[new_active].clear()
+        self._set_active(new_active)
+
+        self._refresh_line(current)
+        self._refresh_line(new_active)
+
+    def _set_active(self, index: int) -> None:
+        item = self._line_items[index]
+        item.setPen(self._active_pen)
+        item.setZValue(10)
+
+    def _set_inactive(self, index: int) -> None:
+        item = self._line_items[index]
+        item.setPen(self._inactive_pen)
+        item.setZValue(1)
+
+    def _update_stepper_display(self, stepper: tuple[Any, ...]) -> None:
+        if not self._stepper_keys:
+            self._set_status_message("")
+            return
+        parts = [f"{key}={value}" for key, value in zip(self._stepper_keys, stepper)]
+        self._set_status_message(" | ".join(parts))
+
+    def _set_status_message(self, message: str) -> None:
+        if hasattr(self, "_status_label"):
+            self._status_label.setText(message)
+
+    def _ingest_row(self, row: Mapping[str, Any]) -> None:
+        if not self._indeps:
+            return
+
+        x_key = self._indeps[0]
+        if x_key not in row:
+            return
+
+        x_value = _safe_float(row.get(x_key))
+        if x_value is None:
+            return
+
+        stepper = tuple(row.get(key) for key in self._stepper_keys)
+        dependent_values = {
+            key: value
+            for key, value in row.items()
+            if key not in self._indeps
+        }
+        if not dependent_values:
+            return
+
+        if self._last_stepper_values is None:
+            self._last_stepper_values = stepper
+        elif stepper != self._last_stepper_values:
+            self._roll_lines()
+            self._last_stepper_values = stepper
+
+        line_idx = self._active_index
+        self._line_storage[line_idx].append({
+            "x": x_value,
+            "values": dict(dependent_values),
+        })
+
+        self._dependent_keys.update(dependent_values.keys())
+        selection_changed, _ = self._sync_y_selector()
+        if not selection_changed:
+            self._refresh_line(line_idx)
+
+        self._update_stepper_display(stepper)
+
+
+class PlotterCommandServer(QObject):
+    def __init__(self, window: LivePlotterWindow, socket_name: str) -> None:
+        super().__init__(window)
+        self._window = window
+        self._socket_name = socket_name
+        self._server = QLocalServer(self)
+        self._connections: set[PlotterConnection] = set()
+
+        QLocalServer.removeServer(self._socket_name)
+
+        if not self._server.listen(self._socket_name):
+            warnings.warn(
+                f"LivePlotter IPC listen failed on '{self._socket_name}': {self._server.errorString()}",
+                stacklevel=2,
+            )
+            return
+
+        self._server.newConnection.connect(self._on_new_connection)
+
+    def _on_new_connection(self) -> None:
+        while self._server.hasPendingConnections():
+            socket = self._server.nextPendingConnection()
+            connection = PlotterConnection(socket, self._window, self)
+            connection.finished.connect(self._on_connection_finished)
+            self._connections.add(connection)
+
+    def _on_connection_finished(self, connection: "PlotterConnection") -> None:
+        self._connections.discard(connection)
+        connection.deleteLater()
+
+
+class PlotterConnection(QObject):
+    finished = Signal(object)
+
+    def __init__(
+        self,
+        socket: QLocalSocket,
+        window: LivePlotterWindow,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self._socket = socket
+        self._window = window
+        self._buffer = bytearray()
+        self._expected_size: int | None = None
+
+        self._socket.readyRead.connect(self._on_ready_read)
+        self._socket.disconnected.connect(self._on_disconnected)
+        self._socket.errorOccurred.connect(self._on_error)
+
+    def _on_ready_read(self) -> None:
+        while self._socket.bytesAvailable():
+            data = self._socket.readAll()
+            if not data:
+                break
+            self._buffer.extend(bytes(data))
+            self._process_buffer()
+
+    def _process_buffer(self) -> None:
+        while True:
+            if self._expected_size is None:
+                if len(self._buffer) < HEAD_LENGTH:
+                    return
+                header = bytes(self._buffer[:HEAD_LENGTH])
+                self._expected_size = int.from_bytes(header, byteorder="big", signed=False)
+                del self._buffer[:HEAD_LENGTH]
+
+            if len(self._buffer) < (self._expected_size or 0):
+                return
+
+            payload = bytes(self._buffer[: self._expected_size]) if self._expected_size else b""
+            del self._buffer[: self._expected_size or 0]
+            self._expected_size = None
+            if payload:
+                self._process_payload(payload)
+
+    def _process_payload(self, payload: bytes) -> None:
+        try:
+            message = pickle.loads(payload)
+        except Exception as exc:  # pragma: no cover - defensive
+            self._send_error("invalid_payload", f"Failed to unpickle payload: {exc}")
+            return
+
+        if not isinstance(message, dict):
+            self._send_error("invalid_message", "Payload must be a dict")
+            return
+
+        command = message.get("cmd")
+        if command == "set_indeps":
+            self._handle_set_indeps(message)
+        elif command == "add":
+            self._handle_add(message)
+        else:
+            self._send_error("unknown_command", f"Command '{command}' is not supported")
+
+    def _handle_set_indeps(self, payload: dict[str, Any]) -> None:
+        indeps = payload.get("indeps")
+        if not isinstance(indeps, Sequence):
+            self._send_error("invalid_arguments", "'indeps' must be a sequence of strings")
+            return
+        try:
+            self._window.set_indeps(list(indeps))
+        except Exception as exc:  # pragma: no cover - GUI validation
+            self._send_error("execution_error", f"{type(exc).__name__}: {exc}")
+            return
+        self._send_packet({"status": "ok", "cmd": "set_indeps"})
+
+    def _handle_add(self, payload: dict[str, Any]) -> None:
+        record = payload.get("record")
+        if record is not None and not isinstance(record, (Mapping, pd.Series)):
+            self._send_error("invalid_arguments", "'record' must be a mapping or pandas Series")
+            return
+
+        seg_payload = payload.get("seg")
+        seg_df = None
+        if seg_payload is not None:
+            if isinstance(seg_payload, pd.DataFrame):
+                seg_df = seg_payload
+            else:
+                try:
+                    seg_df = pd.DataFrame(seg_payload)
+                except (TypeError, ValueError) as exc:
+                    self._send_error("invalid_arguments", f"'seg' conversion failed: {exc}")
+                    return
+
+        try:
+            self._window.add(record=record, seg=seg_df)
+        except Exception as exc:  # pragma: no cover - GUI validation
+            self._send_error("execution_error", f"{type(exc).__name__}: {exc}")
+            return
+
+        self._send_packet({"status": "ok", "cmd": "add"})
+
+    def _send_packet(self, payload: dict[str, Any]) -> None:
+        try:
+            body = pickle.dumps(payload, protocol=pickle.HIGHEST_PROTOCOL)
+        except Exception as exc:  # pragma: no cover - defensive
+            body = pickle.dumps(
+                {"status": "error", "code": "encoding_error", "message": str(exc)},
+                protocol=pickle.HIGHEST_PROTOCOL,
+            )
+        header = len(body).to_bytes(HEAD_LENGTH, byteorder="big", signed=False)
+        self._socket.write(header)
+        if body:
+            self._socket.write(body)
+        self._socket.flush()
+
+    def _send_error(self, code: str, message: str) -> None:
+        self._send_packet({"status": "error", "code": code, "message": message})
+
+    def _on_disconnected(self) -> None:
+        self.finished.emit(self)
+        self._socket.deleteLater()
+        self.deleteLater()
+
+    def _on_error(self, _error: QLocalSocket.LocalSocketError) -> None:  # pragma: no cover - best effort
+        self.finished.emit(self)
+        self._socket.deleteLater()
+        self.deleteLater()
+
+
+class LivePlotterClient:
+    def __init__(
+        self,
+        socket_name: str = LIVE_PLOTTER_PIPE_NAME,
+        *,
+        timeout_ms: int = 5000,
+    ) -> None:
+        self._socket_name = socket_name
+        self._timeout_ms = timeout_ms
+        self._socket: QLocalSocket | None = None
+        self._owns_app = False
+        self._app: QCoreApplication | None = None
+
+    def connect(self) -> None:
+        self._ensure_app()
+        if self._socket is not None and self._socket.state() == QLocalSocket.ConnectedState:
+            return
+
+        socket = QLocalSocket()
+        socket.connectToServer(self._socket_name)
+        if not socket.waitForConnected(self._timeout_ms):
+            error = socket.errorString()
+            socket.deleteLater()
+            raise ConnectionError(f"Could not connect to LivePlotter server '{self._socket_name}': {error}")
+
+        self._socket = socket
+
+    def close(self) -> None:
+        if self._socket is None:
+            return
+        self._socket.disconnectFromServer()
+        self._socket.waitForDisconnected(100)
+        self._socket.deleteLater()
+        self._socket = None
+
+    # Context manager helpers -------------------------------------------------
+    def __enter__(self) -> "LivePlotterClient":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    # IPC commands ------------------------------------------------------------
+    def set_indeps(self, indeps: Sequence[str]) -> None:
+        payload = {"cmd": "set_indeps", "indeps": list(indeps)}
+        self._invoke(payload)
+
+    def add(
+        self,
+        *,
+        record: Mapping[str, Any] | pd.Series | None = None,
+        seg: pd.DataFrame | Mapping[str, Any] | Sequence[Mapping[str, Any]] | None = None,
+    ) -> None:
+        seg_payload: Any = None
+        if seg is not None and not isinstance(seg, pd.DataFrame):
+            try:
+                seg_payload = pd.DataFrame(seg)
+            except (TypeError, ValueError) as exc:
+                raise ValueError("'seg' must be convertible to a pandas DataFrame") from exc
+        else:
+            seg_payload = seg
+
+        if record is not None and not isinstance(record, (Mapping, pd.Series)):
+            raise TypeError("'record' must be a mapping or pandas Series")
+
+        payload = {"cmd": "add", "record": record, "seg": seg_payload}
+        self._invoke(payload)
+
+    # Internal client helpers -------------------------------------------------
+    def _ensure_app(self) -> None:
+        app = QCoreApplication.instance()
+        if app is None:
+            self._app = QCoreApplication([])
+            self._owns_app = True
+        else:
+            self._app = app
+
+    def _invoke(self, payload: dict[str, Any]) -> dict[str, Any]:
+        if self._socket is None:
+            raise RuntimeError("LivePlotterClient is not connected")
+
+        body = pickle.dumps(payload, protocol=pickle.HIGHEST_PROTOCOL)
+        header = len(body).to_bytes(HEAD_LENGTH, byteorder="big", signed=False)
+        self._socket.write(header)
+        if body:
+            self._socket.write(body)
+        if not self._socket.waitForBytesWritten(self._timeout_ms):
+            raise TimeoutError("Timed out sending data to LivePlotter server")
+
+        response = self._read_packet()
+        status = response.get("status")
+        if status != "ok":
+            code = response.get("code", "unknown_error")
+            message = response.get("message", "Request failed")
+            raise RuntimeError(f"LivePlotter error ({code}): {message}")
+        return response
+
+    def _read_packet(self) -> dict[str, Any]:
+        if self._socket is None:
+            raise RuntimeError("LivePlotterClient is not connected")
+
+        header = self._read_exact(HEAD_LENGTH)
+        size = int.from_bytes(header, byteorder="big", signed=False)
+        body = self._read_exact(size) if size else b""
+        if not body:
+            return {}
+        return pickle.loads(body)
+
+    def _read_exact(self, size: int) -> bytes:
+        if self._socket is None:
+            raise RuntimeError("LivePlotterClient is not connected")
+
+        data = bytearray()
+        while len(data) < size:
+            chunk = self._socket.read(size - len(data))
+            if chunk:
+                data.extend(bytes(chunk))
+                continue
+            if not self._socket.waitForReadyRead(self._timeout_ms):
+                raise TimeoutError("Timed out waiting for LivePlotter response")
+            if self._socket.state() != QLocalSocket.ConnectedState and not self._socket.bytesAvailable():
+                raise ConnectionError("LivePlotter server disconnected")
+        return bytes(data)
+
+
+def main() -> None:
+    app = QApplication.instance()
+    owns_app = False
+    if app is None:
+        app = QApplication(sys.argv)
+        owns_app = True
+
+    window = LivePlotterWindow()
+    window.show()
+
+    if owns_app:
+        sys.exit(app.exec())
+
+
+__all__ = ["LivePlotterWindow", "LivePlotterClient", "main"]

logqbit/logfolder.py

@@ -0,0 +1,256 @@
+import inspect
+import itertools
+import os
+import socket
+import threading
+import time
+import weakref
+from datetime import datetime
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+import pandas as pd
+from tqdm import tqdm
+from tqdm.contrib.logging import logging_redirect_tqdm
+
+from .registry import Registry, get_parser
+
+yaml = get_parser()
+
+
+class LogFolder:
+    create_machine = socket.gethostname()  # Can be overridden.
+
+    def __init__(
+        self,
+        path: str | Path,
+        create: bool = True,
+        save_delay_secs: float = 1.0,
+    ):
+        path = Path(path)
+        meta_path = path / "meta.yaml"
+        data_path = path / "data.parquet"
+        if path.exists() and path.is_dir():
+            pass
+        elif create:
+            path.mkdir(parents=True, exist_ok=True)
+            with open(meta_path, "w", encoding="utf-8") as f:
+                yaml.dump(
+                    {
+                        "create_time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                        "create_machine": self.create_machine,
+                    },
+                    f,
+                )
+        else:
+            raise FileNotFoundError(f"LogFolder at '{path}' does not exist.")
+
+        self.path = path
+
+        if meta_path.exists():
+            self.reg = Registry(meta_path, auto_reload=False)
+        else:
+            self.reg = None
+
+        self._handler = _DataHandler(data_path, save_delay_secs, self)
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """Get the full dataframe, flushing all data rows."""
+        return self._handler.get_df()
+
+    @property
+    def meta_path(self) -> Path:
+        return self.reg.path
+
+    @property
+    def data_path(self) -> Path:
+        return self._handler.path
+
+    @classmethod
+    def new(cls, parent_path: Path) -> "LogFolder":
+        parent_path = Path(parent_path)
+        max_index = max(
+            (
+                int(entry.name)
+                for entry in os.scandir(parent_path)
+                if entry.is_dir() and entry.name.isdecimal()
+            ),
+            default=-1,
+        )
+        new_index = max_index + 1
+        while (parent_path / str(new_index)).exists():
+            new_index += 1
+        new_folder = parent_path / str(new_index)
+        return cls(new_folder)
+
+    def add_row(self, **kwargs) -> None:
+        """
+        Add a new row or multiple rows to the dataframe.
+        Supports both scalar and vector input.
+        For vector input, pandas will check length consistency.
+        """
+        is_multi_row = [
+            k
+            for k, v in kwargs.items()
+            if hasattr(v, "__len__") and not isinstance(v, str)
+        ]
+        if is_multi_row:
+            self._handler.add_multi_rows(pd.DataFrame(kwargs))
+        else:
+            self._handler.add_one_row(kwargs)
+
+    def capture(
+        self,
+        func: Callable[[float], dict[str, float | list[float]]],
+        axes: list[float | list[float]] | dict[str, float | list[float]],
+    ):
+        if not isinstance(axes, dict):  # Assumes isinstance(axes, list)
+            fsig = inspect.signature(func)
+            axes = dict(zip(fsig.parameters.keys(), axes))
+
+        run_axs: dict[str, list[float]] = {}
+        const_axs: dict[str, float] = {}
+        for k, v in axes.items():
+            if np.iterable(v):
+                run_axs[k] = v
+            else:
+                const_axs[k] = v
+        self.add_meta_to_head(
+            const=const_axs,
+            dims={k: [min(a), max(a), len(a)] for k, a in run_axs.items()},
+        )
+
+        step_table = list(itertools.product(*run_axs.values()))
+
+        with logging_redirect_tqdm():
+            for step in tqdm(step_table, ncols=80, desc=self.path.name):
+                step_kws = dict(zip(run_axs.keys(), step))
+                ret_kws = func(**step_kws, **const_axs)
+                self.add_row(**step_kws, **ret_kws)
+
+    def add_meta(self, meta: dict = None, /, **kwargs):
+        if meta is None:
+            meta = {}
+        meta.update(kwargs)
+        self.reg.root.update(meta)
+        self.reg.save()
+
+    def add_meta_to_head(self, meta: dict = None, /, **kwargs):
+        if meta is None:
+            meta = {}
+        meta.update(kwargs)
+        for i, (k, v) in enumerate(meta.items()):
+            self.reg.root.insert(i, k, v)
+        self.reg.save()
+
+    @property
+    def indeps(self) -> list[str]:
+        """Running axes for plotting."""
+        return self.reg["indeps"]  # Let KeyError raise if not exists.
+
+    @indeps.setter
+    def indeps(self, value: list[str]) -> None:
+        if not isinstance(value, list):
+            raise ValueError("indeps must be a list of strings.")
+        if not all(isinstance(v, str) for v in value):
+            raise ValueError("indeps must be a list of strings.")
+
+        self.reg["indeps"] = value
+
+    def flush(self) -> None:
+        """Flash the pending data immediately, block until done."""
+        self._handler.flush()
+
+
+class _DataHandler:
+    def __init__(self, path: str | Path, save_delay_secs: float, parent: LogFolder):
+        self.path = Path(path)
+        self._segs: list[pd.DataFrame] = []
+        if self.path.exists():
+            self._segs.append(pd.read_parquet(self.path))
+        self._records: list[dict[str, float | int | str]] = []
+
+        self.save_delay_secs = save_delay_secs
+        self._should_stop = False
+        self._skip_debounce = EventWithWaitingState()
+        self._dirty = EventWithWaitingState()
+        self._lock = threading.Lock()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        weakref.finalize(parent, self._cleanup)
+
+    def get_df(self, _clear: bool = False) -> pd.DataFrame:
+        with self._lock:
+            if self._records:
+                self._segs.append(pd.DataFrame.from_records(self._records))
+                self._records = []
+
+            if len(self._segs) == 0:
+                df = pd.DataFrame({})
+            elif len(self._segs) == 1:
+                df = self._segs[0]
+            else:
+                df = pd.concat(self._segs)
+                self._segs = [df]
+
+            if _clear:
+                self._dirty.clear()
+        return df
+
+    def add_one_row(self, kwargs: dict[str, float | int | str]):
+        with self._lock:
+            self._records.append(kwargs)
+            if not self._dirty.is_set():
+                self._dirty.set()
+
+    def add_multi_rows(self, df: pd.DataFrame):
+        with self._lock:
+            if self._records:
+                self._segs.append(pd.DataFrame.from_records(self._records))
+                self._records = []
+            self._segs.append(df)
+            if not self._dirty.is_set():
+                self._dirty.set()
+
+    def _run(self):
+        while not self._should_stop:
+            self._dirty.wait()
+            if self._should_stop:
+                break
+            if self._skip_debounce.wait(self.save_delay_secs):
+                self._skip_debounce.clear()
+            df = self.get_df(_clear=True)
+            tmp_path = self.path.with_suffix(".tmp")
+            df.to_parquet(tmp_path, index=False)
+            tmp_path.replace(self.path)
+
+    def _cleanup(self):
+        try:
+            self._should_stop = True
+            self._skip_debounce.set()  # Process all pending data.
+            self._dirty.set()  # Just break the run loop.
+            if self._thread.is_alive():
+                self._thread.join(timeout=2)
+        except Exception:
+            pass
+
+    def flush(self):
+        """Flash the pending data immediately, block until done."""
+        if self._skip_debounce.waiting:
+            self._skip_debounce.set()
+        while not self._dirty.waiting:
+            time.sleep(0.01)
+
+
+class EventWithWaitingState(threading.Event):
+    def __init__(self):
+        super().__init__()
+        self.waiting = False
+
+    def wait(self, timeout: float | None = None):
+        self.waiting = True
+        ret = super().wait(timeout)
+        self.waiting = False
+        return ret

logqbit/registry.py

@@ -0,0 +1,229 @@
+import re
+import sys
+import warnings
+from collections.abc import Mapping, Sequence, Set
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+from typing_extensions import deprecated
+
+if TYPE_CHECKING:
+    from ruamel.yaml.constructor import BaseConstructor
+    from ruamel.yaml.nodes import ScalarNode, SequenceNode
+    from ruamel.yaml.representer import BaseRepresenter
+
+_sentinel = object()
+
+
+class FileSnap:
+    __slots__ = ("path", "mtime", "size")
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        st = self.path.stat()
+        self.mtime = st.st_mtime
+        self.size = st.st_size
+
+    def changed(self) -> bool:
+        st = self.path.stat()
+        if (st.st_mtime, st.st_size) != (self.mtime, self.size):
+            self.mtime = st.st_mtime
+            self.size = st.st_size
+            return True
+        return False
+
+
+class Registry:
+    """A simple registry based on YAML file.
+
+    `get`/`set` values synchronized with the file unless explicitly calling `get_local`/`set_local`.
+    ```python
+    reg = Registry('config.yaml')
+    reg['new_key/sub_key'] = 123  # synced with file
+    ```
+
+    Operations on `root` and subitems are **local** and needs to be saved manually. e.g.
+    ```python
+    reg.reload()
+    reg.root['another_key'] = 456  # local change, not synced until save.
+    reg.save()
+    ```
+    Local changes will be discarded when `reload()`.
+
+    NOTE: Local operations is useful for batch update without frequent file I/O.
+    """
+
+    def __init__(self, path: str | Path, auto_reload: bool = True):
+        self.path = Path(path)
+        self.yaml = get_parser()
+        self.root: CommentedMap = None
+        self.load()
+        self._snap = FileSnap(self.path)
+        self.auto_reload = auto_reload
+
+    def __getitem__(self, key: str):
+        return self.get(key)
+
+    def __setitem__(self, key: str, value):
+        self.set(key, value, create_parents=True)
+
+    def get(self, key: str, default=_sentinel):
+        if self.auto_reload: self.reload()
+        return self.get_local(key, default)
+
+    def set(self, key: str, value, create_parents: bool = True):
+        if self.auto_reload: self.reload()
+        self.set_local(key, value, create_parents)
+        self.save()
+
+    def get_local(self, key: str, default=_sentinel):
+        obj = self.root
+        keys = key.split("/")
+        for k in keys:
+            try:
+                obj = obj[k]
+            except (KeyError, IndexError, TypeError):
+                if default is _sentinel:
+                    raise
+                return default
+        return obj
+
+    def set_local(self, key: str, value, create_parents: bool = True):
+        obj = self.root
+        keys = key.split("/")
+        for k in keys[:-1]:
+            if not (k in obj and isinstance(obj[k], Mapping)):
+                if create_parents:
+                    obj[k] = CommentedMap()
+                else:
+                    raise KeyError(f"Parent key '{k}' does not exist.")
+            obj = obj[k]
+        obj[keys[-1]] = value
+
+    def print_local(self):
+        """Print the local content to stdout."""
+        self.yaml.dump(self.root, sys.stdout)
+
+    def reload(self):
+        """Reloads the file if it has changed since the last load."""
+        if self._snap.changed():
+            self.load()
+        return self.root
+
+    def load(self):
+        """Load YAML file to self.root."""
+        # NOTE: `yaml.load` also returns `CommentedSeq`, `float`, `str`, `None`
+        # or other build-in types depending on the top-level YAML content. But
+        # only `CommentedMap` is legal for the use case of this class.
+        with open(self.path, "r", encoding="utf-8") as f:
+            self.root = self.yaml.load(f)
+        return self.root
+
+    def save(self, path: str | Path | None = None):
+        """Save self.root to YAML file."""
+        path = self.path if path is None else path
+        tmp_path = path.with_suffix('.tmp')
+        with open(tmp_path, "w", encoding="utf-8") as f:
+            self.yaml.dump(self.root, f)
+        tmp_path.replace(path)
+
+    @deprecated("For backward compatibility only.")
+    def copy(self) -> dict:
+        if self.auto_reload: self.reload()
+        return _to_builtins(self.root)
+
+    @deprecated("For backward compatibility only.")
+    def cwd(self) -> str:
+        return self["data_folder"]
+
+
+def get_parser() -> YAML:
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    yaml.width = 100
+    yaml.indent(mapping=2, sequence=4, offset=2)
+    yaml.representer.add_representer(np.ndarray, _represent_numpy_array)
+    yaml.representer.add_multi_representer(np.generic, _represent_numpy_scalar)
+    _set_yaml_for_labrad_units(yaml)
+    return yaml
+
+def _represent_numpy_array(dumper: "BaseRepresenter", data: np.ndarray):
+    # return dumper.represent_sequence("!numpy", data.tolist(), flow_style=True)
+    return dumper.represent_sequence("tag:yaml.org,2002:seq", data.tolist(), flow_style=True)
+
+def _represent_numpy_scalar(dumper: "BaseRepresenter", data: np.generic):
+    return dumper.represent_data(data.item())
+
+
+####### labrad.units support #########
+
+
+def _set_yaml_for_labrad_units(yaml: YAML) -> YAML:
+    return yaml  # placeholder if labrad is not available
+
+
+try:
+    import labrad.units as lab_units
+    from labrad.units import Unit, Value, WithUnit
+
+    def _set_yaml_for_labrad_units(yaml: YAML) -> YAML:
+        yaml.resolver.add_implicit_resolver(
+            "!labrad_unit", _UNIT_PATTERN, list("+-0123456789")
+        )
+        yaml.constructor.add_constructor("!labrad_unit", _construct_labrad_value)
+        yaml.representer.add_representer(WithUnit, _represent_labrad_value)
+        yaml.representer.add_representer(Value, _represent_labrad_value)
+except ImportError:
+    warnings.warn("labrad.units not found, unit support disabled.", ImportWarning)
+
+
+_UNIT_PATTERN = re.compile(r"^\s*([-+]?\d[\d_]*(?:\.\d[\d_]*)?)\s*([A-Za-z]*)\s*$")
+
+
+def _construct_labrad_value(loader: "BaseConstructor", node: "ScalarNode"):
+    raw: str = loader.construct_scalar(node)
+    match = _UNIT_PATTERN.match(raw)
+    if not match:
+        return raw
+
+    magnitude_raw, unit_name = match.groups()
+    unit_obj: Unit | None = getattr(lab_units, unit_name, None)
+    if unit_obj is None:
+        return raw
+
+    magnitude = float(magnitude_raw.replace("_", ""))
+    return magnitude * unit_obj
+
+
+def _represent_labrad_value(dumper: "BaseRepresenter", data: WithUnit):
+    unit_name = data.unit.name
+    magnitude: float = data._value
+    if magnitude.is_integer():
+        spaced = f"{int(magnitude)} {unit_name}"
+    else:
+        spaced = f"{magnitude} {unit_name}"
+    # spaced = str(data)
+    # return dumper.represent_scalar('tag:yaml.org,2002:str', "="+spaced, style="")
+    return dumper.represent_scalar("!labrad_unit", spaced)
+
+
+def _to_builtins(obj):
+    if isinstance(obj, Mapping):
+        return {_to_builtins(k): _to_builtins(v) for k, v in obj.items()}
+    if isinstance(obj, Sequence) and not isinstance(obj, (str, bytes)):
+        # BUG: labRAD dump tuple only, remove it!!
+        return tuple(_to_builtins(item) for item in obj)
+    if isinstance(obj, Set):
+        return {_to_builtins(item) for item in obj}
+
+    if isinstance(obj, int):
+        return int(obj)
+    if isinstance(obj, float):
+        return float(obj)
+    if isinstance(obj, str):
+        return str(obj)
+
+    return obj

logqbit-0.0.1.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.3
+Name: logqbit
+Version: 0.0.1
+Summary: Simple data logger and live plotter for lab-scale experiments.
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pyarrow>=21.0.0
+Requires-Dist: pyqtgraph>=0.13.7
+Requires-Dist: pyside6>=6.9.3
+Requires-Dist: ruamel-yaml>=0.18.15
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: pylabrad>=0.98.3 ; extra == 'labrad'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/Qiujv/logqbit
+Provides-Extra: labrad
+Description-Content-Type: text/markdown
+
+# LogQbit
+
+*LogQbit* 是一个轻量且可扩展的实验数据记录工具包。
+它最初用于记录 量子比特（qubit）实验测量数据，但凭借灵活的数据格式和实时可视化功能，同样适用于 任意中小规模（≤MB级）实验数据 的采集与管理。
+
+*LogQbit* is a lightweight and extensible data logging toolkit for lab-scale experiments.
+It was originally developed for recording quantum qubit measurement data, 
+but its flexible format and real-time visualization tools make it suitable for any small to medium (≤MB-level) experimental dataset.
+
+通过使用 `logqbit`，你可以：
+
+- 以最少的样板代码记录结构化实验数据；
+
+- 使用集成的实时绘图工具可视化数据流；
+
+- 通过交互式日志浏览器查看与分析记录的数据。
+
+With `logqbit`, you can:
+
+- Record structured experimental data with minimal boilerplate.
+
+- Visualize data streams in real time with an integrated live plotter.
+
+- Browse and analyze logged results through an interactive log browser.
+
+无论是量子比特读出、参数扫描，还是传感器输出记录，
+`logqbit` 都能为你提供一个简洁而可靠的实验数据采集与回溯工作流。
+
+Whether you are monitoring qubit readouts, scanning a parameter sweep, or simply logging sensor outputs, 
+`logqbit` provides a simple and robust workflow for capturing and revisiting your experimental data.

logqbit-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+logqbit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+logqbit/assets/icon.svg,sha256=RJ-_0hYbS1YZMOXAAmkHrPfs9CcvEvHCguIQwfzs2mw,721
+logqbit/browser.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+logqbit/constants.py,sha256=r0-qpPMaVOqwfdfY0oDBOU70DIHLTLhGiGUtd8pH_Fw,179
+logqbit/live_plotter.py,sha256=I7Njn4aTAuEZSATrI637fJPpmSZw2FvR597eUWu850s,23581
+logqbit/logfolder.py,sha256=LbAAW1UME61ENjsGu48ywXCS4ODtOqcD8KLa1LRbKU0,8073
+logqbit/registry.py,sha256=8sTFkKY9T_oez6BptVWEBUcvppi4nLeziZaEahZTNLc,7475
+logqbit-0.0.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+logqbit-0.0.1.dist-info/entry_points.txt,sha256=ePkNeOIr9vbB1rNUAUEXXCoOali6KolvradqAcnUKno,64
+logqbit-0.0.1.dist-info/METADATA,sha256=i1b_3afutfferwqVZ9tKL77OckP50JRppbpAQky_Upw,1957
+logqbit-0.0.1.dist-info/RECORD,,

logqbit-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

logqbit-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[gui_scripts]
+logqbit-live-plotter = logqbit.live_plotter:main
+