QuLab 2.11.8__tar.gz → 2.11.9__tar.gz

{qulab-2.11.8 → qulab-2.11.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QuLab
-Version: 2.11.8
+Version: 2.11.9
 Summary: contral instruments and manage data
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>

{qulab-2.11.8 → qulab-2.11.9}/QuLab.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QuLab
-Version: 2.11.8
+Version: 2.11.9
 Summary: contral instruments and manage data
 Author-email: feihoo87 <feihoo87@gmail.com>
 Maintainer-email: feihoo87 <feihoo87@gmail.com>

{qulab-2.11.8 → qulab-2.11.9}/QuLab.egg-info/SOURCES.txt

@@ -108,5 +108,4 @@ qulab/visualization/qdat.py
 qulab/visualization/rot3d.py
 qulab/visualization/widgets.py
 src/qulab.h
-tests/test_kad.py
 tests/test_scan.py

{qulab-2.11.8 → qulab-2.11.9}/qulab/executor/analyze.py

@@ -4,6 +4,7 @@ import time
 
 import pyperclip
 import zmq
+from rich import print
 
 from .storage import Report
 

{qulab-2.11.8 → qulab-2.11.9}/qulab/executor/cli.py

@@ -25,7 +25,12 @@ from .utils import workflow_template
 
 @logger.catch(reraise=True)
 def run_script(script_path, extra_paths=None):
-    """Run a script in a new process, inheriting current PYTHONPATH plus any extra paths."""
+    """Run a script in a new process, inheriting current PYTHONPATH plus any extra paths.
+    
+    Args:
+        script_path (str): Path to the script to be executed
+        extra_paths (list, optional): Additional paths to be added to PYTHONPATH
+    """
     import subprocess
     import sys
 
@@ -103,8 +108,17 @@ def command_option(command_name):
               help='The path of the code.')
 @log_options('create')
 def create(workflow, code):
-    """
-    Create a new workflow file.
+    """Create a new workflow file.
+    
+    This command creates a new workflow file with a template structure. The template includes
+    basic workflow setup and any unreferenced workflows as potential dependencies.
+    
+    Args:
+        workflow: Name of the workflow to create
+        code: Directory path where the workflow file will be created. Defaults to current directory.
+    
+    Example:
+        $ qulab create my_workflow --code ./workflows
     """
     logger.info(f'[CMD]: create {workflow} --code {code}')
     if code is None:
@@ -133,8 +147,19 @@ def create(workflow, code):
               help='The modlule name of the api.')
 @log_options('set')
 def set(key, value, api):
-    """
-    Set a config.
+    """Set a configuration value in the registry.
+    
+    This command allows you to set key-value pairs in the configuration registry.
+    The value can be any valid Python expression that can be evaluated.
+    
+    Args:
+        key: The configuration key to set
+        value: The value to set (can be a Python expression)
+        api: Optional API module for custom config handling
+    
+    Example:
+        $ qulab set Q1.channel.Z NS_DDS.CH1
+        $ qulab set gate.R.Q3.params.frequency 5.0e9
     """
     logger.info(f'[CMD]: reg set {key} {value} --api {api}')
     reg = Registry()
@@ -157,8 +182,17 @@ def set(key, value, api):
               help='The modlule name of the api.')
 @log_options('get')
 def get(key, api):
-    """
-    Get a config.
+    """Get a configuration value from the registry.
+    
+    Retrieves and displays the value associated with a given key from the configuration registry.
+    
+    Args:
+        key: The configuration key to retrieve
+        api: Optional API module for custom config handling
+    
+    Example:
+        $ qulab get Q1.channel
+        $ qulab get gate.R.Q3.params.frequency
     """
     logger.info(f'[CMD]: reg get {key} --api {api}')
     reg = Registry()
@@ -177,8 +211,16 @@ def get(key, api):
               help='The modlule name of the api.')
 @log_options('delete')
 def delete(key, api):
-    """
-    Delete a config key.
+    """Delete a configuration key from the registry.
+    
+    Removes a key and its associated value from the configuration registry.
+    
+    Args:
+        key: The configuration key to delete
+        api: Optional API module for custom config handling
+    
+    Example:
+        $ qulab delete gate.R.Q3.params.block_freq
     """
     logger.info(f'[CMD]: reg delete {key} --api {api}')
     reg = Registry()
@@ -201,8 +243,24 @@ def delete(key, api):
               help='The format of the config.')
 @log_options('export')
 def export(file, api, format):
-    """
-    Export a config.
+    """Export the configuration registry to a file.
+    
+    Exports all configuration settings to a file in the specified format.
+    
+    Args:
+        file: Path to the output file
+        api: Optional API module for custom config handling
+        format: Output format (pickle, json, or yaml)
+    
+    Supported formats:
+        - pickle: Binary format (default)
+        - json: JSON text format
+        - yaml: YAML text format
+    
+    Example:
+        $ qulab export config.pkl
+        $ qulab export config.json --format json
+        $ qulab export config.yaml --format yaml
     """
     logger.info(f'[CMD]: reg export {file} --api {api}')
     reg = Registry()
@@ -239,8 +297,27 @@ def export(file, api, format):
               help='The format of the config.')
 @log_options('load')
 def load(file, api, format):
-    """
-    Load a config.
+    """Load configuration settings from a file.
+    
+    Imports configuration settings from a file in the specified format.
+    Existing configuration will be cleared before loading the new settings.
+    
+    Args:
+        file: Path to the input file or report index number
+        api: Optional API module for custom config handling
+        format: Input format (pickle, json, yaml, or report)
+    
+    Supported formats:
+        - pickle: Binary format (default)
+        - json: JSON text format
+        - yaml: YAML text format
+        - report: Load from a saved report by index
+    
+    Example:
+        $ qulab load config.pkl
+        $ qulab load config.json --format json
+        $ qulab load config.yaml --format yaml
+        $ qulab load 123 --format report  # Load from report #123
     """
     logger.info(f'[CMD]: reg load {file} --api {api}')
     reg = Registry()
@@ -278,8 +355,16 @@ def load(file, api, format):
               default=lambda: get_config_value("bootstrap", Path),
               help='The path of the bootstrap.')
 def boot(bootstrap):
-    """
-    Run a bootstrap script.
+    """Run a bootstrap script.
+    
+    Executes a bootstrap script to set up the environment or perform initialization tasks.
+    The bootstrap script runs in a new process with the current Python environment.
+    
+    Args:
+        bootstrap: Path to the bootstrap script
+    
+    Example:
+        $ qulab boot --bootstrap setup.py
     """
     if bootstrap is not None:
         run_script(bootstrap)
@@ -291,7 +376,16 @@ def parse_dynamic_option_value(value):
         parsed_value = ast.literal_eval(value)
     except (ValueError, SyntaxError):
         # 如果解析失败，返回原始字符串
-        parsed_value = value
+        if ',' in value:
+            parsed_value = []
+            for item in value.split(','):
+                try:
+                    parsed_value.append(ast.literal_eval(item))
+                except (ValueError, SyntaxError):
+                    parsed_value.append(item)
+            parsed_value = tuple(parsed_value)
+        else:
+            parsed_value = value
     return parsed_value
 
 
@@ -311,17 +405,31 @@ def parse_dynamic_options(args):
     return result
 
 
-help_doc = """
-Run a workflow.
+help_doc = """Run a workflow with specified parameters and options.
+
+This command executes a workflow and its dependencies based on the provided configuration.
+
+Arguments:
+    workflow: The name or path of the workflow to run
+
+Options:
+    --code, -c: The path containing the workflow code (default: current directory)
+    --data, -d: The path for storing logs and data (default: ./logs)
+    --api, -a: The module name of the API for configuration handling
+    --plot, -p: Generate plots after workflow execution
+    --no-dependents, -n: Run only the specified workflow without dependencies
+    --retry, -r: Number of retry attempts for failed calibrations (default: 1)
+    --freeze: Freeze the configuration table during execution
+    --fail-fast, -f: Stop execution on first error
+    --veryfy-source-code: Verify source code before execution
 
-If the workflow has entries, run all entries.
-If `--no-dependents` is set, only run the workflow itself.
-If `--retry` is set, retry the workflow when calibration failed.
-If `--freeze` is set, freeze the config table.
-If `--plot` is set, plot the report.
-If `--api` is set, use the api to get and update the config table.
-If `--code` is not set, use the current working directory.
-If `--data` is not set, use the `logs` directory in the code path.
+Additional parameters can be passed as key=value pairs and will be available to the workflow.
+
+Examples:
+    $ qulab run my_workflow
+    $ qulab run my_workflow --plot --retry 3
+    $ qulab run my_workflow param1=value1 param2=value2
+    $ qulab run my_workflow --no-dependents --freeze
 """
 
 
@@ -478,15 +586,30 @@ async def maintain(workflow,
                    plot,
                    fail_fast,
                    veryfy_source_code=True):
-    """
-    Maintain a workflow.
-
-    If the workflow has entries, run all entries.
-    If `--retry` is set, retry the workflow when calibration failed.
-    If `--plot` is set, plot the report.
-    If `--api` is set, use the api to get and update the config table.
-    If `--code` is not set, use the current working directory.
-    If `--data` is not set, use the `logs` directory in the code path.
+    """Maintain a workflow and its dependencies.
+    
+    This command checks and maintains the workflow and its dependencies without executing them.
+    It verifies configurations, dependencies, and can generate plots from existing data.
+    
+    Args:
+        workflow: Name or path of the workflow to maintain
+        code: Directory containing the workflow code
+        data: Directory for logs and data
+        api: Module name for configuration API
+        retry: Number of retry attempts for failed calibrations
+        plot: Generate plots from existing data
+        fail_fast: Stop on first error
+        veryfy_source_code: Verify source code integrity
+    
+    The maintenance process includes:
+        1. Verifying workflow dependencies
+        2. Checking configuration consistency
+        3. Validating source code (if enabled)
+        4. Generating plots (if enabled)
+    
+    Example:
+        $ qulab maintain my_workflow --retry 3 --plot
+        $ qulab maintain my_workflow --fail-fast
     """
     logger.info(
         f'[CMD]: maintain {workflow} --code {code} --data {data} --api {api}'
@@ -556,13 +679,28 @@ async def maintain(workflow,
 @command_option('reproduce')
 @async_command
 async def reproduce(report_id, code, data, api, plot):
-    """
-    Reproduce a report.
-
-    If `--plot` is set, plot the report.
-    If `--api` is set, use the api to get and update the config table.
-    If `--code` is not set, use the current working directory.
-    If `--data` is not set, use the `logs` directory in the code path.
+    """Reproduce a workflow execution from a saved report.
+    
+    This command loads a previous execution report and attempts to reproduce the workflow
+    with the exact same configuration and conditions.
+    
+    Args:
+        report_id: The ID number of the report to reproduce
+        code: Directory containing the workflow code
+        data: Directory for logs and data
+        api: Module name for configuration API
+        plot: Generate plots after reproduction
+    
+    The reproduction process:
+        1. Loads the original report by ID
+        2. Restores the exact configuration state
+        3. Executes the workflow with frozen configuration
+        4. Optionally generates plots
+        5. Restores the previous configuration state
+    
+    Example:
+        $ qulab reproduce 123 --plot
+        $ qulab reproduce 456 --code ./workflows --data ./results
     """
     logger.info(
         f'[CMD]: reproduce {report_id} --code {code} --data {data} --api {api}'

{qulab-2.11.8 → qulab-2.11.9}/qulab/executor/utils.py

@@ -38,6 +38,7 @@ import numpy as np
 from loguru import logger
 
 from qulab import VAR
+from qulab import manual_analysis
 from qulab.typing import Report
 
 
@@ -73,7 +74,8 @@ async def analyze(report: Report, history: Report | None = None) -> Report:
     history: Report | None
         上次校准实验数据和分析结果，如果有的话。
     \"\"\"
-    import random
+    # 如果需要手动分析，请取消注释下面这行
+    # return manual_analysis(report, history)
 
     # 这里添加你的分析过程，运行 calibrate 得到的数据，在 report.data 里
     # 你可以得到校准的结果，然后根据这个结果进行分析。
@@ -82,6 +84,7 @@ async def analyze(report: Report, history: Report | None = None) -> Report:
     # 完整校准后的状态有两种：OK 和 Bad，分别对应校准成功和校准失败。
     # 校准失败是指出现坏数据，无法简单通过重新运行本次校准解决，需要
     # 检查前置步骤。
+    import random
     report.state = random.choice(['OK', 'Bad'])
 
     # 参数是一个字典，包含了本次校准得到的参数，后续会更新到config表中。
@@ -144,7 +147,7 @@ async def oracle(report: Report,
     
     当校准失败时，根据 analyze 的结果，尝试改变某些配置再重新校准整个系统。
     比如通常我们在死活测不到 rabi 或能谱时，会换一个 idle bias 再试试。这
-    里我们凭直觉设的那个 bias 值，就是一个谕示，可以通过 oracle 来设定。
+    里我们凭直觉设的那个 bias 值，就称作一个谕示，可以通过 oracle 来设定。
 
     该函数代入的参数 report 是 analyze 函数的返回值。
     \"\"\"
@@ -161,6 +164,17 @@ async def debug_analyze(
         code_path: str | Path = get_config_value('code', Path),
         data_path: str | Path = get_config_value('data', Path),
 ) -> None:
+    """
+    调试 workflow 的分析过程。
+
+    该函数会从 data_path 中读取报告，并重新加载对应的 workflow 代码，然后
+    运行 analyze 函数，如果有 plot 函数，还会运行 plot 函数。最后返回包含
+    分析结果的 report 对象。
+
+    当你完成一个 workflow 的 calibrate 开发后，可以现运行该 workflow 采
+    集一组数据，然后通过反复修改 analyze 函数，运行该函数，并查看分析结果，
+    来调试 analyze 函数，以期达到满意的效果。
+    """
     from .storage import get_report_by_index
 
     report = get_report_by_index(report_index, data_path)

qulab-2.11.9/qulab/monitor/__init__.py

@@ -0,0 +1 @@
+from .monitor import MonitorUI, get_monitor

qulab-2.11.9/qulab/monitor/__main__.py

@@ -0,0 +1,36 @@
+"""
+QuLab Monitor Command Line Interface
+
+This module provides a command-line interface for launching the QuLab monitor.
+It allows users to start a standalone monitor server with configurable settings.
+"""
+
+import click
+
+from .monitor import MonitorServer
+
+
+@click.command(name='monitor')
+@click.option('--columns', '-c', default=4, help='Number of columns in the plot grid')
+@click.option('--height', '-h', default=400, help='Minimum height of each plot in pixels')
+@click.option('--address', '-a', default='127.0.0.1', help='Address to bind the server')
+@click.option('--port', '-p', default=5555, help='Port to bind the server')
+def main(columns: int, height: int, address: str, port: int):
+    """Launch a QuLab monitor server.
+
+    Args:
+        columns: Number of columns in the plot grid
+        height: Minimum height of each plot in pixels
+        address: Address to bind the server (default: 127.0.0.1)
+        port: Port to bind the server (default: 5555)
+    """
+    server = MonitorServer(address=address, 
+                         port=port,
+                         number_of_columns=columns, 
+                         minimum_height=height)
+    try:
+        while True:
+            import time
+            time.sleep(1)  # Keep the script running while the server is active
+    except KeyboardInterrupt:
+        print("\nShutting down monitor server...")

qulab-2.11.9/qulab/monitor/config.py

@@ -0,0 +1,66 @@
+"""
+QuLab Monitor Configuration Module
+
+This module defines the global configuration settings for the QuLab monitor
+application, including:
+- Visual styles and themes
+- Data transformation functions
+- Plot appearance settings
+- Buffer sizes and indices
+
+The configuration values are used throughout the monitor application to maintain
+consistent appearance and behavior.
+"""
+
+from typing import Callable, Dict, List, Tuple, Union
+import numpy as np
+
+# Qt stylesheet for the application
+STYLE = '''
+QWidget {
+    font: medium Ubuntu;
+    background-color: #011F2F;
+    font-size: 16px;
+    color: #FFFFFF;
+}
+'''
+
+# Number of data frames to keep in the rolling buffer
+ROLL_BUFFER_SIZE = 6
+
+# Data transformation functions for complex data visualization
+DataTransform = Callable[[Union[np.ndarray, list], float], np.ndarray]
+
+TRANSFORMS: Dict[str, DataTransform] = {
+    "mag": lambda data, _: np.abs(data),
+    "phase": lambda data, _: np.angle(data),
+    "real": lambda data, _: np.real(data),
+    "imag": lambda data, _: np.imag(data),
+    "rot": lambda data, angle: np.real(np.exp(1j * angle) * np.array(data))
+}
+
+# List of available transformation names
+TRANSFORM_NAMES: List[str] = list(TRANSFORMS.keys())
+
+# Colors for selected and unselected states (RGB values)
+COLOR_SELECTED: Tuple[int, int, int] = (0, 0, 0)
+COLOR_UNSELECTED: Tuple[int, int, int] = (6, 6, 8)
+
+# Default colors for plot lines (RGB values)
+DEFAULT_COLORS: List[Tuple[int, int, int]] = [
+    (200, 0, 0),    # Bright red
+    (55, 100, 180), # Blue
+    (40, 80, 150),  # Medium blue
+    (30, 50, 110),  # Dark blue
+    (25, 40, 70),   # Navy
+    (25, 30, 50),   # Dark navy
+]
+
+# Line widths for each plot line
+LINE_WIDTHS: List[int] = [3, 2, 2, 2, 1, 1]
+
+# Symbol sizes for each plot line (0 means no symbols)
+SYMBOL_SIZES: List[int] = [5, 0, 0, 0, 0, 0]
+
+# Reversed indices for the rolling buffer (newest to oldest)
+ROLL_INDICES: List[int] = list(range(ROLL_BUFFER_SIZE))[::-1]

qulab-2.11.9/qulab/monitor/dataset.py

@@ -0,0 +1,184 @@
+"""
+QuLab Monitor Dataset Module
+
+This module provides data management functionality for the QuLab monitor application.
+It handles storage and retrieval of time-series data with support for both point-by-point
+and trace-based data collection.
+
+The Dataset class maintains a rolling buffer of data frames, where each frame can
+contain multiple named columns of numerical data.
+"""
+
+from collections import defaultdict, deque
+from typing import Union, Sequence
+
+from .config import ROLL_BUFFER_SIZE
+
+PAUSE_TIME = 1
+
+Number = Union[int, float, complex]
+DataPoint = Union[Number, Sequence[Number]]
+DataFrame = Union[Sequence[Number], Sequence[Sequence[Number]]]
+
+
+def remove_duplicates(input_list: list[str]) -> list[str]:
+    """
+    Remove duplicates from a list of strings while preserving order.
+
+    Args:
+        input_list: List of strings that may contain duplicates
+
+    Returns:
+        List of unique strings in their original order
+    """
+    return list(dict.fromkeys(input_list))
+
+
+class Dataset:
+    """
+    A data management class for storing and retrieving time-series data.
+
+    This class maintains a rolling buffer of data frames, where each frame
+    contains multiple columns of numerical data. It supports both point-by-point
+    data collection and trace-based data collection.
+
+    Attributes:
+        column_names: List of column names for the dataset
+        box: Rolling buffer containing data frames
+        dirty: Flag indicating if data has been modified since last read
+    """
+
+    def __init__(self):
+        """Initialize an empty dataset with a rolling buffer."""
+        self.column_names: list[str] = []
+        self.box: deque[dict] = deque(maxlen=ROLL_BUFFER_SIZE)
+        self.dirty: bool = True
+
+    def clear(self) -> None:
+        """Clear all data from the dataset."""
+        self.box.clear()
+
+    def clear_history(self) -> None:
+        """
+        Clear historical data while preserving the most recent frame.
+        
+        This is useful for maintaining the current state while discarding
+        historical data that is no longer needed.
+        """
+        if self.box:
+            current_frame = self.box.popleft()
+            self.box.clear()
+            self.box.appendleft(current_frame)
+
+    def set_column_names(self, column_names: list[str]) -> None:
+        """
+        Set or update the column names for the dataset.
+
+        If the new column names differ from the current ones, all existing
+        data will be cleared to maintain consistency.
+
+        Args:
+            column_names: List of unique column names
+        """
+        column_names = remove_duplicates(column_names)
+        if column_names != self.column_names:
+            self.clear()
+        self.column_names = column_names
+
+    def get_data(self, step: int, x_name: str,
+                 y_name: str) -> tuple[list[Number], list[Number]]:
+        """
+        Retrieve X-Y data pairs from a specific step in the dataset.
+
+        Args:
+            step: Index of the data frame to retrieve
+            x_name: Name of the column to use for X values
+            y_name: Name of the column to use for Y values
+
+        Returns:
+            Tuple containing lists of X and Y values. Returns empty lists if
+            the requested step is not available.
+        """
+        try:
+            frame = self.box[step]
+            return frame[x_name], frame[y_name]
+        except IndexError:
+            return [], []
+
+    def append(self, dataframe: DataFrame) -> None:
+        """
+        Append new data to the dataset.
+
+        This method automatically determines whether the input is point data
+        or trace data based on its structure.
+
+        Args:
+            dataframe: Either a list of values for point data or a list of
+                      lists for trace data. The length must match the number
+                      of columns.
+
+        Raises:
+            AssertionError: If the input data length doesn't match the number
+                           of columns.
+            TypeError: If the input data format is invalid.
+        """
+        if not dataframe:
+            return
+        try:
+            # Test if dataframe is a list of lists (trace data)
+            iter(dataframe[0])
+            self._append_traces(dataframe)
+        except TypeError:
+            self._append_points(dataframe)
+
+    def roll(self) -> None:
+        """
+        Add a new empty frame to the dataset.
+        
+        This creates a new defaultdict that will automatically create empty
+        lists for any new column names accessed.
+        """
+        self.box.appendleft(defaultdict(list))
+
+    def _append_points(self, points: Sequence[Number]) -> None:
+        """
+        Append point data to the current frame.
+
+        Args:
+            points: List of values, one for each column
+
+        Raises:
+            AssertionError: If the number of points doesn't match the number
+                           of columns
+        """
+        self.dirty = True
+        if len(points) != len(self.column_names):
+            raise AssertionError(
+                "Point data length mismatch\n"
+                f"Expected {len(self.column_names)} values for columns: {self.column_names}\n"
+                f"Received {len(points)} values: {points}"
+            )
+        
+        for name, value in zip(self.column_names, points):
+            self.box[0][name].append(value)
+
+    def _append_traces(self, traces: Sequence[Sequence[Number]]) -> None:
+        """
+        Append trace data as a new frame.
+
+        Args:
+            traces: List of data sequences, one for each column
+
+        Raises:
+            AssertionError: If the number of traces doesn't match the number
+                           of columns
+        """
+        self.dirty = True
+        if len(traces) != len(self.column_names):
+            raise AssertionError(
+                "Trace data length mismatch\n"
+                f"Expected {len(self.column_names)} sequences for columns: {self.column_names}\n"
+                f"Received {len(traces)} sequences"
+            )
+        
+        self.box.appendleft(dict(zip(self.column_names, traces)))