QuLab 2.11.7__py3-none-any.whl → 2.11.9__py3-none-any.whl

qulab/monitor/monitor.py

@@ -1,5 +1,17 @@
+"""
+QuLab Monitor Module
+
+This module provides real-time data visualization capabilities for QuLab.
+It implements a multiprocessing-based monitoring system that can display
+multiple data streams in a configurable grid layout.
+
+Classes:
+    Monitor: Main class for creating and managing the monitoring window
+"""
+
 import multiprocessing as mp
 import sys
+import zmq
 
 # try:
 #     mp.set_start_method("spawn")
@@ -7,19 +19,40 @@ import sys
 #     pass
 
 
-def main(queue: mp.Queue,
-         ncols: int = 4,
+def main(data_queue: mp.Queue,
+         num_columns: int = 4,
          minimum_height: int = 400,
-         colors: list[tuple[int, int, int]] = []):
+         plot_colors: list[tuple[int, int, int]] = []) -> None:
+    """
+    Initialize and run the main monitoring window.
+
+    Args:
+        data_queue: Multiprocessing queue for data communication
+        num_columns: Number of columns in the plot grid layout
+        minimum_height: Minimum height of each plot in pixels
+        plot_colors: List of RGB color tuples for plot lines
+    """
     from .mainwindow import MainWindow
     from .qt_compat import QtWidgets
 
     app = QtWidgets.QApplication(sys.argv)
-    main = MainWindow(queue, ncols, minimum_height, colors)
+    main_window = MainWindow(data_queue, num_columns, minimum_height, plot_colors)
     sys.exit(app.exec())
 
 
-class Monitor():
+class MonitorUI:
+    """
+    Real-time data monitoring interface.
+    
+    This class manages a separate process that displays real-time data plots
+    in a grid layout. Data can be added through various methods and will be
+    displayed immediately.
+
+    Args:
+        number_of_columns: Number of columns in the plot grid layout
+        minimum_height: Minimum height of each plot in pixels
+        colors: List of RGB color tuples for plot lines
+    """
 
     def __init__(self,
                  number_of_columns: int = 4,
@@ -32,72 +65,203 @@ class Monitor():
         self.process = None
         self.start()
 
-    def start(self):
+    def start(self) -> None:
+        """Start the monitoring process if not already running."""
         if self.process is not None and self.process.is_alive():
             return
         self.queue = mp.Queue(20)
         self.process = mp.Process(target=main,
-                                  args=(self.queue, self.number_of_columns,
-                                        self.minimum_height, self.colors))
+                                args=(self.queue, self.number_of_columns,
+                                     self.minimum_height, self.colors))
         self.process.start()
 
-    def _put(self, w: tuple):
-        self.queue.put(w)
+    def _put(self, message: tuple) -> None:
+        """Send a message to the monitoring process."""
+        self.queue.put(message)
 
-    def roll(self):
+    def roll(self) -> None:
+        """Clear and reset all plots."""
         self._put(("ROLL", None))
 
-    def set_column_names(self, *arg):
-        self._put(('PN', list(arg)))
+    def set_column_names(self, *column_names) -> None:
+        """Set the names of data columns for plotting."""
+        self._put(('PN', list(column_names)))
 
-    def add_point(self, *arg):
-        self._put(('PD', list(arg)))
+    def add_point(self, *values) -> None:
+        """Add a new data point to the plots."""
+        self._put(('PD', list(values)))
 
-    def set_plots(self, arg):
+    def set_plots(self, plot_config: str) -> None:
         """
-        arg: str, like "(x,y)" or "(x1,y1);(x2,y2);"
+        Configure which columns to plot against each other.
+
+        Args:
+            plot_config: String specifying plot configurations, e.g. "(x,y)" or "(x1,y1);(x2,y2);"
         """
-        self._put(('PXY', str(arg)))
+        self._put(('PXY', str(plot_config)))
 
-    def set_trace_column_names(self, *arg):
-        self._put(('TN', list(arg)))
+    def set_trace_column_names(self, *column_names) -> None:
+        """Set the names of trace data columns."""
+        self._put(('TN', list(column_names)))
 
-    def add_trace(self, *arg):
-        self._put(('TD', list(arg)))
+    def add_trace(self, *values) -> None:
+        """Add a new trace data point."""
+        self._put(('TD', list(values)))
 
-    def set_trace_plots(self, arg):
+    def set_trace_plots(self, plot_config: str) -> None:
         """
-        arg: str, like "(x,y)" or "(x1,y1);(x2,y2);"
+        Configure which columns to plot for traces.
+
+        Args:
+            plot_config: String specifying trace plot configurations, e.g. "(x,y)" or "(x1,y1);(x2,y2);"
         """
-        self._put(('TXY', str(arg)))
+        self._put(('TXY', str(plot_config)))
+
+    def is_alive(self) -> bool:
+        """Check if the monitoring process is running."""
+        return self.process.is_alive()
 
     def __del__(self):
+        """Clean up resources when the Monitor object is deleted."""
         try:
             self.process.kill()
         except:
             pass
 
-    def is_alive(self):
-        return self.process.is_alive()
+
+class Monitor:
+    def __init__(self, address: str="127.0.0.1", port: int=5555):
+        self.context = zmq.Context()
+        self.socket = self.context.socket(zmq.REQ)
+        self.socket.connect(f"tcp://{address}:{port}")
+
+    def _send_command(self, cmd: str, data=None) -> None:
+        try:
+            self.socket.send_pyobj((cmd, data))
+            response = self.socket.recv_string()
+            if response.startswith("Error"):
+                raise RuntimeError(response)
+        except Exception as e:
+            raise RuntimeError(f"Failed to send command: {str(e)}")
+
+    def roll(self) -> None:
+        self._send_command("ROLL", None)
+
+    def set_column_names(self, *column_names) -> None:
+        self._send_command("PN", list(column_names))
+
+    def add_point(self, *values) -> None:
+        self._send_command("PD", list(values))
+
+    def set_plots(self, plot_config: str) -> None:
+        self._send_command("PXY", plot_config)
+
+    def set_trace_column_names(self, *column_names) -> None:
+        self._send_command("TN", list(column_names))
+
+    def add_trace(self, *values) -> None:
+        self._send_command("TD", list(values))
+
+    def set_trace_plots(self, plot_config: str) -> None:
+        self._send_command("TXY", plot_config)
+
+    def __del__(self):
+        try:
+            self.socket.close()
+            self.context.term()
+        except:
+            pass
 
 
+class MonitorServer:
+    def __init__(self, address: str="*", port: int=5555, number_of_columns: int = 4,
+                 minimum_height: int = 400,
+                 colors: list[tuple[int, int, int]] = []):
+        self.address = address
+        self.port = port
+        self.number_of_columns = number_of_columns
+        self.minimum_height = minimum_height
+        self.colors = colors
+        self.running = True
+        self.process = mp.Process(target=self._run)
+        self.process.start()
+
+    def _run(self):
+        try:
+            # Create Monitor instance in the child process
+            self.monitor = MonitorUI(self.number_of_columns, self.minimum_height, self.colors)
+            
+            # Create ZMQ context and socket in the child process
+            self.context = zmq.Context()
+            self.socket = self.context.socket(zmq.REP)
+            self.socket.bind(f"tcp://{self.address}:{self.port}")
+
+            while self.running:
+                try:
+                    message = self.socket.recv_pyobj()
+                    cmd, data = message
+                    if cmd == 'ROLL':
+                        self.monitor.roll()
+                    elif cmd == 'PN':
+                        self.monitor.set_column_names(*data)
+                    elif cmd == 'PD':
+                        self.monitor.add_point(*data)
+                    elif cmd == 'PXY':
+                        self.monitor.set_plots(data)
+                    elif cmd == 'TN':
+                        self.monitor.set_trace_column_names(*data)
+                    elif cmd == 'TD':
+                        self.monitor.add_trace(*data)
+                    elif cmd == 'TXY':
+                        self.monitor.set_trace_plots(data)
+                    self.socket.send_string("OK")
+                except Exception as e:
+                    self.socket.send_string(f"Error: {str(e)}")
+        finally:
+            # Clean up resources in child process
+            try:
+                self.socket.close()
+                self.context.term()
+            except:
+                pass
+
+    def __del__(self):
+        self.running = False
+        try:
+            self.process.terminate()
+            self.process.join()
+        except:
+            pass
+
+
+# Global monitor instance
 _monitor = None
 
 
-def get_monitor(auto_open=True):
+def get_monitor(auto_open: bool = True) -> MonitorUI:
+    """
+    Get or create a global Monitor instance.
+
+    Args:
+        auto_open: If True, create a new Monitor if none exists or if existing one is not running
+
+    Returns:
+        Monitor instance
+    """
     global _monitor
 
     if auto_open and (_monitor is None or not _monitor.is_alive()):
-        _monitor = Monitor()
+        _monitor = MonitorUI()
 
     return _monitor
 
 
 if __name__ == "__main__":
+    # Example usage and testing code
     import time
-
     import numpy as np
 
+    # Example 1: Using Monitor directly
     for i in range(3):
         index = 0
         while True:
@@ -113,3 +277,29 @@ if __name__ == "__main__":
             m.add_point(index, np.random.randn(), np.sin(index / 20))
             index += 1
             time.sleep(0.2)
+
+    # Example 2: Using MonitorServer and Monitor
+    def run_server():
+        server = MonitorServer("127.0.0.1", 5555)
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            pass
+
+    def run_client():
+        client = Monitor("127.0.0.1", 5555)
+        time.sleep(1)  # Wait for server to start
+        
+        client.set_column_names("index", "H", "S")
+        client.set_plots("(index,H);(index,S)")
+        client.roll()
+        
+        for i in range(100):
+            client.add_point(i, np.random.randn(), np.sin(i / 20))
+            time.sleep(0.2)
+
+    if len(sys.argv) > 1 and sys.argv[1] == "server":
+        run_server()
+    elif len(sys.argv) > 1 and sys.argv[1] == "client":
+        run_client()

qulab/monitor/ploter.py

@@ -1,123 +1,148 @@
-from .config import COL_SEL, COL_UNSEL, SymSize, defualt_colors, ridx, widths
+"""
+QuLab Monitor Plotter Module
+
+This module provides a custom plotting widget based on pyqtgraph for real-time
+data visualization. It includes features like auto-ranging, mouse interaction
+for data selection, and clipboard integration.
+"""
+
+from .config import (COLOR_SELECTED, COLOR_UNSELECTED, SYMBOL_SIZES,
+                    DEFAULT_COLORS, ROLL_INDICES, LINE_WIDTHS)
 from .qt_compat import QtWidgets
 
 # the plotting widget
 try:
     import pyqtgraph as pg
-except:
+except ImportError:
     raise ImportError("Please install pyqtgraph first")
 
 try:
     import pyperclip as pc
-    hasCliper = True
-except:
-    hasCliper = False
+    HAS_CLIPBOARD = True
+except ImportError:
+    HAS_CLIPBOARD = False
 
 
 class PlotWidget(pg.PlotWidget):
+    """
+    Custom plotting widget extending pyqtgraph's PlotWidget.
+
+    This widget provides additional features like:
+    - Configurable plot colors and styles
+    - Mouse interaction for data point selection
+    - Clipboard integration for selected data points
+    - Auto-ranging and axis control
+
+    Args:
+        minimum_height: Minimum height of the plot widget in pixels
+        colors: List of RGB color tuples for plot lines
+    """
 
     def __init__(self, minimum_height=300, colors=None):
-        self.XAxisLinked = False
-        self.YAxisLinked = False
+        self.x_axis_linked = False
+        self.y_axis_linked = False
         if colors is None:
-            colors = defualt_colors
-        elif len(colors) < len(defualt_colors):
-            colors.extend(defualt_colors[len(colors):])
+            colors = DEFAULT_COLORS
+        elif len(colors) < len(DEFAULT_COLORS):
+            colors.extend(DEFAULT_COLORS[len(colors):])
         self.colors = colors
-        self.xname = ""
-        self.yname = ""
+        self.x_name = ""
+        self.y_name = ""
         super().__init__()
 
         self.setMinimumHeight(minimum_height)
         self.showGrid(x=True, y=True)
-        self.setBackground(COL_UNSEL)
+        self.setBackground(COLOR_UNSELECTED)
 
         self.plotItem.vb.autoRange()
 
         ## Labeling
-        self.XLabel = QtWidgets.QLabel(self)
-        self.XLabel.setText("X:")
-        self.XLabel.move(0, 5)
-        self.YLabel = QtWidgets.QLabel(self)
-        self.YLabel.setText("Y:")
-        self.YLabel.move(0, 35)
+        self.x_label = QtWidgets.QLabel(self)
+        self.x_label.setText("X:")
+        self.x_label.move(0, 5)
+        self.y_label = QtWidgets.QLabel(self)
+        self.y_label.setText("Y:")
+        self.y_label.move(0, 35)
 
         self.plots = {}
-        self.clippos1 = 0
-        self.clippos2 = 0
+        self.clip_pos_start = 0
+        self.clip_pos_end = 0
         self.range_select = False
-        for i in ridx:
-            self.plots[i] = \
-              self.plot([],[] ,pen={"color":self.colors[i]  ,"width":widths[i]} ,
-                  symbolBrush = self.colors[i],
-                  symbolPen = { "width":0 ,"color":self.colors[i] }   ,
-                  symbolSize =SymSize[i] ,
+        for idx in ROLL_INDICES:
+            self.plots[idx] = \
+              self.plot([],[] ,pen={"color":self.colors[idx]  ,"width":LINE_WIDTHS[idx]} ,
+                  symbolBrush = self.colors[idx],
+                  symbolPen = { "width":0 ,"color":self.colors[idx] }   ,
+                  symbolSize =SYMBOL_SIZES[idx] ,
               )
         self.update()
 
-    def set_X_label(self, w):
-        self.xname = w
-        self.XLabel.setText(f"X:{w}")
+    def set_x_label(self, label: str) -> None:
+        """Set the X-axis label."""
+        self.x_name = label
+        self.x_label.setText(f"X:{label}")
 
-    def set_Y_label(self, w):
-        self.yname = w
-        self.YLabel.setText(f"Y:{w}")
+    def set_y_label(self, label: str) -> None:
+        """Set the Y-axis label."""
+        self.y_name = label
+        self.y_label.setText(f"Y:{label}")
 
-    def auto_range(self):
+    def auto_range(self) -> None:
+        """Automatically adjust plot range to show all data."""
         self.plotItem.vb.autoRange()
 
-    def enable_auto_range(self):
+    def enable_auto_range(self) -> None:
+        """Enable automatic range adjustment."""
         self.plotItem.vb.enableAutoRange()
 
-    def keyPressEvent(self, ev):
-        #print(ev.text());
-        tx = ev.text()
-        if ('f' == tx or 'F' == tx):
+    def keyPressEvent(self, event):
+        """Handle keyboard events for plot control.
+        
+        Keys:
+            F/f: Auto-range the plot
+            A/a: Enable auto-pan
+            R/r: Enable range selection mode
+        """
+        key = event.text().lower()
+        if key == 'f':
             self.plotItem.vb.autoRange()
-        if ('a' == tx or 'A' == tx):
+        elif key == 'a':
             self.plotItem.vb.setAutoPan()
-        if ('r' == tx or 'R' == tx):
+        elif key == 'r':
             self.range_select = True
-        super().keyPressEvent(ev)
+        super().keyPressEvent(event)
 
-    def keyReleaseEvent(self, ev):
-        #print(ev.text());
-        tx = ev.text()
-        if ('f' == tx or 'F' == tx):
-            self.plotItem.vb.autoRange()
-        if ('a' == tx or 'A' == tx):
-            self.plotItem.vb.setAutoPan()
-        if ('r' == tx or 'R' == tx):
+    def keyReleaseEvent(self, event):
+        """Handle key release events."""
+        key = event.text().lower()
+        if key == 'r':
             self.range_select = False
-        super().keyReleaseEvent(ev)
-
-    def mousePressEvent(self, ev):
-        if (4 == ev.button()):
-            # print(ev.flags())
-            if (hasCliper):
-                # print("Mouse is pressed")
-                self.clippos1 = self.plotItem.vb.mapSceneToView(ev.pos()).x()
+        super().keyReleaseEvent(event)
+
+    def mousePressEvent(self, event):
+        """Handle mouse press events for data selection."""
+        if event.button() == 4 and HAS_CLIPBOARD:
+            self.clip_pos_start = self.plotItem.vb.mapSceneToView(event.pos()).x()
         else:
-            super().mousePressEvent(ev)
-
-    def mouseReleaseEvent(self, ev):
-        if (4 == ev.button()):
-            p = ev.pos()
-            if (hasCliper):
-                # print("Mouse is released")
-                self.clippos2 = self.plotItem.vb.mapSceneToView(ev.pos()).x()
-                if (self.range_select):
-                    pc.copy(f"{self.clippos1},{self.clippos2}")
-                else:
-                    pc.copy(self.clippos2)
+            super().mousePressEvent(event)
+
+    def mouseReleaseEvent(self, event):
+        """Handle mouse release events and copy selected data to clipboard."""
+        if event.button() == 4 and HAS_CLIPBOARD:
+            self.clip_pos_end = self.plotItem.vb.mapSceneToView(event.pos()).x()
+            if self.range_select:
+                pc.copy(f"{self.clip_pos_start},{self.clip_pos_end}")
+            else:
+                pc.copy(str(self.clip_pos_end))
         else:
-            super().mouseReleaseEvent(ev)
+            super().mouseReleaseEvent(event)
 
     def update(self):
         super().update()
 
-    def set_data(self, i, x, y):
-        self.plots[i].setData(x, y)
+    def set_data(self, index: int, x_data, y_data) -> None:
+        """Update plot data for the specified index."""
+        self.plots[index].setData(x_data, y_data)
 
     # def mouseDoubleClickEvent(self, ev):
     #     super().mouseDoubleClickEvent(ev)

qulab/monitor/qt_compat.py

@@ -1,16 +1,45 @@
+"""
+QuLab Monitor Qt Compatibility Module
+
+This module provides compatibility layer for Qt constants and enums across
+different Qt bindings (PyQt5, PyQt6, PySide2, PySide6). It ensures consistent
+access to Qt constants regardless of the Qt binding being used.
+
+The module exports the following constants:
+- AlignRight: Right alignment flag
+- BottomDockWidgetArea: Bottom dock widget area constant
+- ScrollBarAlwaysOn: Always show scrollbar policy
+- ScrollBarAlwaysOff: Never show scrollbar policy
+- TopDockWidgetArea: Top dock widget area constant
+"""
+
 from matplotlib.backends.qt_compat import QT_API, QtCore, QtWidgets
 
+# Define Qt constants based on the Qt binding being used
 if QT_API in ['PySide6', 'PyQt6']:
+    # Qt6 uses enum flags
     AlignRight = QtCore.Qt.AlignmentFlag.AlignRight
     BottomDockWidgetArea = QtCore.Qt.DockWidgetArea.BottomDockWidgetArea
     ScrollBarAlwaysOn = QtCore.Qt.ScrollBarPolicy.ScrollBarAlwaysOn
     ScrollBarAlwaysOff = QtCore.Qt.ScrollBarPolicy.ScrollBarAlwaysOff
     TopDockWidgetArea = QtCore.Qt.DockWidgetArea.TopDockWidgetArea
 elif QT_API in ['PyQt5', 'PySide2']:
+    # Qt5 uses direct constants
     AlignRight = QtCore.Qt.AlignRight
     BottomDockWidgetArea = QtCore.Qt.BottomDockWidgetArea
     ScrollBarAlwaysOn = QtCore.Qt.ScrollBarAlwaysOn
     ScrollBarAlwaysOff = QtCore.Qt.ScrollBarAlwaysOff
     TopDockWidgetArea = QtCore.Qt.TopDockWidgetArea
 else:
-    raise AssertionError(f"Unexpected QT_API: {QT_API}")
+    raise ValueError(f"Unsupported Qt binding: {QT_API}")
+
+# Export all constants
+__all__ = [
+    'QtCore',
+    'QtWidgets',
+    'AlignRight',
+    'BottomDockWidgetArea',
+    'ScrollBarAlwaysOn',
+    'ScrollBarAlwaysOff',
+    'TopDockWidgetArea',
+]