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

qulab/executor/analyze.py

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

qulab/executor/cli.py

@@ -1,7 +1,9 @@
+import ast
 import functools
 import graphlib
 import importlib
 import os
+import re
 import sys
 from pathlib import Path
 
@@ -23,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
 
@@ -101,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:
@@ -131,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()
@@ -155,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()
@@ -175,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()
@@ -199,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()
@@ -237,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()
@@ -276,14 +355,87 @@ 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)
 
 
-@click.command()
+def parse_dynamic_option_value(value):
+    """解析动态参数值"""
+    try:
+        parsed_value = ast.literal_eval(value)
+    except (ValueError, SyntaxError):
+        # 如果解析失败，返回原始字符串
+        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
+
+
+def parse_dynamic_options(args):
+    """解析格式为 key=value 的未知参数列表"""
+    pattern = re.compile(r'^([a-zA-Z_][\w\-]*)=(.+)$')
+    result = {}
+    for arg in args:
+        match = pattern.match(arg)
+        if match:
+            key, value = match.groups()
+            result[key] = parse_dynamic_option_value(value)
+        else:
+            raise ValueError(
+                f"Invalid argument format: {arg}. Expected format is key=value."
+            )
+    return result
+
+
+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
+
+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
+"""
+
+
+@click.command(context_settings=dict(ignore_unknown_options=True,
+                                     allow_extra_args=True),
+               help=help_doc)
 @click.argument('workflow')
 @click.option('--plot', '-p', is_flag=True, help='Plot the report.')
 @click.option('--no-dependents',
@@ -301,8 +453,10 @@ def boot(bootstrap):
               help='Veryfy the source code.')
 @log_options('run')
 @command_option('run')
+@click.pass_context
 @async_command
-async def run(workflow,
+async def run(ctx,
+              workflow,
               code,
               data,
               api,
@@ -312,18 +466,6 @@ async def run(workflow,
               freeze,
               fail_fast,
               veryfy_source_code=True):
-    """
-    Run a workflow.
-
-    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.
-    """
     logger.info(
         f'[CMD]: run {workflow} --code {code} --data {data} --api {api}'
         f'{" --plot" if plot else ""}'
@@ -342,6 +484,13 @@ async def run(workflow,
     code = Path(os.path.expanduser(code))
     data = Path(os.path.expanduser(data))
 
+    extra_args = ctx.args
+    params = parse_dynamic_options(extra_args)
+
+    if params:
+        workflow = (workflow, params)
+        rich.print(workflow)
+
     wf = load_workflow(workflow, code, veryfy_source_code=veryfy_source_code)
     check_toplogy(wf, code, veryfy_source_code=veryfy_source_code)
 
@@ -437,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}'
@@ -515,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/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/monitor/__init__.py

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

qulab/monitor/__main__.py

@@ -1,8 +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 Monitor
+from .monitor import MonitorServer
 
 
 @click.command(name='monitor')
-def main():
-    pass
+@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/monitor/config.py

@@ -1,41 +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
 
-style = '''
+# Qt stylesheet for the application
+STYLE = '''
 QWidget {
     font: medium Ubuntu;
     background-color: #011F2F;
     font-size: 16px;
-    font-size: 16px;
-    color:#FFFFFF;
+    color: #FFFFFF;
 }
 '''
-#
-Nroll = 6
-
-#  Format of the data.
-forms = {
-    "mag": lambda w, ang: np.abs(w),
-    "phase": lambda w, ang: np.angle(w),
-    "real": lambda w, ang: np.real(w),
-    "imag": lambda w, ang: np.imag(w),
-    "rot": lambda w, ang: np.real(np.exp(1j * ang) * np.array(w))
+
+# 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))
 }
-form_keys = list(forms.keys())
-#
-COL_SEL = (0, 0, 0)
-COL_UNSEL = (6, 6, 8)
-#
-
-defualt_colors = [
-    (200, 0, 0),
-    (55, 100, 180),
-    (40, 80, 150),
-    (30, 50, 110),
-    (25, 40, 70),
-    (25, 30, 50),
+
+# 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
 ]
 
-widths = [3, 2, 2, 2, 1, 1]
-SymSize = [5, 0, 0, 0, 0, 0]
-ridx = list(range(Nroll))
-ridx.reverse()
+# 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]