spinqlablink 包
================

.. module:: spinqlablink
   
spinqlablink 是一个用于连接和控制量子设备的Python包，提供了与SpinQ量子实验设备交互的接口。该包允许用户执行各种量子实验，包括系统初始化、量子门操作、量子电路构建以及量子算法实现等。

主要功能
------------

* 设备连接与管理
* 量子实验执行与控制
* 量子门和量子电路构建
* 脉冲序列定义与操作
* 量子算法实现

基本用法
------------

.. code-block:: python

   from spinqlablink import SpinQLabLink
   
   # Create connection
   spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
   
   # Connect to device
   spinqlablink.connect()
   
   # Wait for login to complete
   if not spinqlablink.wait_for_login():
       print("Login failed")
       return
   
   # Disconnect after use
   spinqlablink.disconnect()

公共函数
------------

.. class:: SpinQLabLink(host, port, account, password)

   SpinQLabLink 类是该包的核心组件，负责管理与量子设备的连接、实验执行和结果获取。
   
   :param host: 设备主机地址
   :type host: str
   :param port: 设备端口号
   :type port: int
   :param account: 用户账号
   :type account: str
   :param password: 用户密码
   :type password: str

   .. method:: connect()

      连接到量子设备。
      
      :return: 连接是否成功
      :rtype: bool

   .. method:: disconnect()

      断开与量子设备的连接。
      
      :return: 断开连接是否成功
      :rtype: bool

   .. method:: wait_for_login(timeout=10)

      等待登录完成，超时时间为10秒。
      
      :param timeout: 超时时间（秒）
      :type timeout: int
      :return: 登录是否成功
      :rtype: bool

   .. method:: get_device()

      获取设备对象，用于访问设备参数和状态。
      
      :return: 设备对象
      :rtype: Device

   .. method:: register_experiment(experiment_type)

      注册一个新的实验。
      
      :param experiment_type: 实验类型
      :type experiment_type: ExperimentType
      :return: 实验对象和参数
      :rtype: tuple

   .. method:: run_experiment()

      运行已注册的实验。

   .. method:: wait_for_experiment_completion()

      等待实验完成。
      
      :return: 实验是否成功完成
      :rtype: bool

   .. method:: get_experiment_result()

      获取实验结果。
      
      :return: 实验结果
      :rtype: dict

   .. method:: deregister_experiment()

      注销当前实验。
      
      :return: 注销是否成功
      :rtype: bool

   .. method:: get_device_status()

      获取设备状态。
      
      :return: 设备状态信息
      :rtype: dict

   .. method:: get_device_frequencies()

      获取设备频率信息。
      
      :return: 设备频率信息
      :rtype: dict

实验类型
------------

.. class:: ExperimentType

   ExperimentType 枚举定义了可用的实验类型。

   .. list-table::
      :header-rows: 1
      :widths: 40 60
   
      * - 属性
        - 描述
      * - ``NMR_PHENOMENON_AND_SIGNAL``
        - 脉冲序列实验
      * - ``RABI_OSCILLATIONS``
        - 拉比振荡实验
      * - ``QUANTUM_BIT``
        - 量子比特操作
      * - ``QUANTUM_DECOHERENCE_T1``
        - T1弛豫测量
      * - ``QUANTUM_DECOHERENCE_T2``
        - T2弛豫测量
      * - ``QUANTUM_CONTROL``
        - 量子控制实验
      * - ``QUANTUM_SYSTEM_INITIALIZATION``
        - 量子系统初始化
      * - ``QUANTUM_GATES_AND_CIRCUIT``
        - 量子门和量子电路操作
      * - ``QUANTUM_STATE_TOMOGRAPHY``
        - 量子态层析
      * - ``QUANTUM_COMPUTING_TASK``
        - 量子计算任务
        
      * - ``INTRODUCTION_TO_QUANTUM_COMPUTING``
        - 量子计算基础实验
      * - ``DEUTSCH_ALGORITHM``
        - Deutsch算法实验
      * - ``BERNSTEIN_VARIRANI_ALGORITHM``
        - Bernstein-Vazirani算法实验
      * - ``GROVER_ALGORITHM``
        - Grover算法实验
      * - ``QFT_ALGORITHM``
        - QFT算法实验
      * - ``HHL_ALGORITHM``
        - HHL算法实验
      * - ``VQE_ALGORITHM``
        - VQE算法实验
      * - ``QAOA_ALGORITHM``
        - QAOA算法实验

      * - ``SPIN_ECHO``
        - 自旋回波实验
      * - ``DYNAMIC_DECOUPLING``
        - 动态解耦实验
      * - ``SHAPE_PULSE``
        - 形状脉冲实验
      * - ``NUMERICAL_OPTIMIZATION_PULSE``
        - 数值优化脉冲实验

      * - ``PHYSICAL_LAYER_EXPERIMENT``
        - 物理层实验
      * - ``CIRCUIT_LAYER_EXPERIMENT``
        - 电路层实验

脉冲操作
------------

.. class:: Pulse(path, phase, amplitude, width, detuning=0)

   Pulse 类用于定义量子操作的脉冲序列。
   
   :param path: 脉冲路径（0表示氢通道，1表示磷通道）[0,1]
   :type path: int
   :param phase: 脉冲相位（度）[0,360]
   :type phase: float
   :param amplitude: 脉冲振幅（百分比）[0,100]
   :type amplitude: float
   :param width: 脉冲宽度（微秒）[0,2000000]
   :type width: float
   :param detuning: 脉冲频率偏移（Hz）[0,10000]
   :type detuning: float

.. code-block:: python

   from spinqlablink import Pulse
   
   # Create a pulse
   pulse = Pulse(path=0, phase=90, amplitude=100, width=40)

.. class:: Gradient(path, amplitude, width)

   Gradient 类用于定义梯度脉冲。
   
   :param path: 梯度路径，默认为1
   :type path: int
   :param amplitude: 梯度振幅 [0,100]
   :type amplitude: float
   :param width: 梯度宽度（微秒）[0,2000000]
   :type width: float

量子门和电路
------------

.. class:: Gate(type, qubitIndex=0, controlQubit=-1, controlQubit2=-1, delay=0, angle=0)

   Gate 类用于定义量子门操作。
   
   :param type: 门类型（如'H', 'X', 'Y', 'Z', 'CNOT'等）['H','I','X','Y','Z','X90','Y90','Z90','Rx','Ry','Rz','T','Td','S','Sd','CNOT','CZ']
   :type type: str
   :param qubitIndex: 量子比特索引
   :type qubitIndex: int
   :param controlQubit: 控制量子比特索引（对于控制门如CNOT）
   :type controlQubit: int
   :param angle: 门角度（度）[0,360]
   :type angle: float
   :param delay: 门延迟（微秒）[0,2000000]
   :type delay: float
   :param timeslot: 门时间槽 [0,60]
   :type timeslot: int
   :param controlQubit2: 第二个控制量子比特索引（对于CNOT门）
   :type controlQubit2: int

.. code-block:: python

   from spinqlablink import Gate
   
   # Create a Hadamard gate acting on qubit 0
   h_gate = Gate(type='H', qubitIndex=0)
   
   # create a Rx gate with angle 90 degrees
   rx_gate = Gate(type='Rx', qubitIndex=0, angle=90)

   # Create a CNOT gate with control qubit 0 and target qubit 1
   cnot_gate = Gate(type='CNOT', qubitIndex=1, controlQubit=0)

.. class:: CustomGate(type, customType, pulses=None, gateJson=None)

   CustomGate 类用于定义自定义量子门。
   
   :param type: 门类型（如'H', 'X', 'Y', 'Z'等）['H','I','X','Y','Z','X90','Y90','Z90','Rx','Ry','Rz','T','Td','S','Sd','CNOT','CZ']
   :type type: str
   :param customType: 自定义门类型名称
   :type customType: str
   :param pulses: 脉冲序列列表
   :type pulses: list[Pulse]
   :param gateJson: 门定义的JSON字符串
   :type gateJson: str

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

gateJson定义的JSON字符串示例:

**注意:读取json文件后输入为字符串形式，不要使用json.loads()函数**

.. code-block:: json
   
   {
      "description": {
         "TITLE": "H2_custom_gate.spinq",
         "TYPE": "",
         "ORIGIN": "",
         "OWNER": "",
         "DATE": "",
         "TIME": "",
         "TOTALPULSEWIDTH": 0,
         "Calibration_Power": 0,
         "SLICES": 0,
         "PULSEWIDTH": 40
      },
      "pulse": {
         "channel1_pulse": [
            {
                  "detuning": 0,
                  "phase": 90.0,
                  "amplitude": 100.0,
                  "width": 40.0
            }
         ],
         "channel2_pulse": [
            {
                  "detuning": 0,
                  "phase": 0.0,
                  "amplitude": 0.0,
                  "width": 40.0
            }
         ]
      }
   }

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

CustomGate的定义示例:

.. code-block:: python

   from spinqlablink import CustomGate, Pulse
   
   # Define a custom Hadamard gate using pulse sequences
   custom_h_gate = CustomGate(
       type='H',
       customType='H_custom_gate',
       pulses=[Pulse(path=0, phase=90, amplitude=100, width=40)]
   )
   
   # Define a custom Hadamard gate using JSON definition (alternative method)
   custom_x_gate = CustomGate(
       type='X',
       customType='X_custom_gate',
       gateJson="{\"description\":{\"TITLE\":\"H2_custom_gate.spinq\",\"TYPE\":\"\",\"ORIGIN\":\"\",\"OWNER\":\"\",\"DATE\":\"\",\"TIME\":\"\",\"TOTALPULSEWIDTH\":0,\"Calibration_Power\":0,\"SLICES\":0,\"PULSEWIDTH\":40},\"pulse\":{\"channel1_pulse\":[{\"detuning\":0,\"phase\":90.0,\"amplitude\":100.0,\"width\":40.0}],\"channel2_pulse\":[{\"detuning\":0,\"phase\":0.0,\"amplitude\":0.0,\"width\":40.0}]}}"
   )

.. class:: Circuit(qubit_count)

   Circuit 类用于构建量子电路。
   
   :param qubit_count: 量子比特数量
   :type qubit_count: int
   
   .. method:: __lshift__(gate)
   
      添加量子门到电路中。
      
      :param gate: 要添加的量子门
      :type gate: Gate or CustomGate
      :return: 电路对象本身
      :rtype: Circuit
   
   .. method:: print_circuit()
   
      打印电路结构。

.. code-block:: python

   from spinqlablink import Circuit, Gate, CustomGate, Pulse
   
   # Create a 2-qubit circuit
   circuit = Circuit(2)
   
   # Add quantum gates
   circuit << Gate(type='H', qubitIndex=0)
   circuit << Gate(type='CNOT', qubitIndex=1, controlQubit=0)
   circuit << CustomGate(
       type='X',
       customType='X_custom_gate',
       qubitIndex=0,
       pulses=[Pulse(path=0, phase=90, amplitude=100, width=80)]
   )
   
   # Print circuit structure
   circuit.print_circuit()

实用工具
------------

.. function:: print_graph(result)

   打印实验结果图表。
   
   :param result: 实验结果
   :type result: dict

.. function:: parse_spinq_file(file_path)

   解析SpinQ文件。
   
   :param file_path: 文件路径
   :type file_path: str
   :return: 解析结果
   :rtype: dict

   文件格式参阅 :class:`CustomGate` 获取更多关于SpinQ文件格式的详细信息。

.. function:: pulse_domain_analysis(pulses)

   对脉冲序列进行域分析。
   
   :param pulses: 脉冲序列
   :type pulses: list[Pulse]
   :return: 分析结果
   :rtype: dict

.. class:: WaveformGenerator

   波形生成器类，用于生成各种波形。
   
   .. method:: generate_gaussian(amplitude, width, sigma)
   
      生成高斯波形。
      
      :param amplitude: 振幅
      :type amplitude: float
      :param width: 宽度
      :type width: float
      :param sigma: 标准差
      :type sigma: float
      :return: 波形数据
      :rtype: list[float]
   
   .. method:: generate_square(amplitude, width)
   
      生成方波。
      
      :param amplitude: 振幅
      :type amplitude: float
      :param width: 宽度
      :type width: float
      :return: 波形数据
      :rtype: list[float]

使用示例
------------

系统初始化实验
^^^^^^^^^^^^^^^

.. code-block:: python

   from spinqlablink import SpinQLabLink, ExperimentType, Pulse
   
   # Create connection
   spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
   spinqlablink.connect()
   
   if not spinqlablink.wait_for_login():
       print("Login failed")
       return
   
   # Register system initialization experiment
   _, exp_sysinit_para = spinqlablink.register_experiment(ExperimentType.QUANTUM_SYSTEM_INITIALIZATION)
   
   # Set experiment parameters
   exp_sysinit_para.repeat = 9
   exp_sysinit_para.pulses = [
       Pulse(path=0, phase=90, amplitude=100, width=40),
       # More pulses...
   ]
   
   # Run experiment
   spinqlablink.run_experiment()
   spinqlablink.wait_for_experiment_completion()
   
   # Get results
   result = spinqlablink.get_experiment_result()
   
   # Cleanup
   spinqlablink.deregister_experiment()
   spinqlablink.disconnect()

量子算法实验
^^^^^^^^^^^^^^^

.. code-block:: python

   from spinqlablink import SpinQLabLink, ExperimentType, Gate, Circuit
   
   # Create connection
   spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
   spinqlablink.connect()
   
   if not spinqlablink.wait_for_login():
       print("Login failed")
       return
   
   # Register quantum algorithm experiment
   _, exp_algorithm_para = spinqlablink.register_experiment(ExperimentType.QUANTUM_ALGORITHM)
   
   # Set algorithm type
   exp_algorithm_para.algorithm_type = ExperimentType.INTRODUCTION_TO_QUANTUM_COMPUTING
   exp_algorithm_para.samplePath = -1
   
   # Create quantum circuit
   circuit = Circuit(2)
   circuit << Gate(type='H', qubitIndex=0)
   circuit << Gate(type='CNOT', qubitIndex=1, controlQubit=0)
   
   # Set circuit
   exp_algorithm_para.set_circuit(circuit)
   
   # Run experiment
   spinqlablink.run_experiment()
   spinqlablink.wait_for_experiment_completion()
   
   # Get results
   result = spinqlablink.get_experiment_result()
   
   # Cleanup
   spinqlablink.deregister_experiment()
   spinqlablink.disconnect()

设备数据监控
^^^^^^^^^^^^^^^

.. code-block:: python

   from spinqlablink import SpinQLabLink
   
   # Data update callback function
   def on_info_update(device, update_type):
       if update_type == 'status':
           print(f"Device status update: Connected={device.status.connected}, Lock={device.status.lock_state}")
       elif update_type == 'lock_data':
           print(f"Lock data update: Frequency0={device.lock_data.frequency0} Hz")
   
   # Create connection
   spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
   spinqlablink.connect()
   
   if not spinqlablink.wait_for_login():
       print("Login failed")
       return
   
   # Get device object and register observer
   device = spinqlablink.get_device()
   device.register_observer(on_info_update)
   
   # Get device parameters
   print("Pulse phases:", device.get_pulse_phases())
   print("Qubit parameters:", device.get_qubit_params())
   
   # Cleanup
   device.unregister_observer(on_info_update)
   spinqlablink.disconnect()