时间调度
本文是 QProg.to_instruction 生成的指令调度数据的解析与绘图 API 参考。
导入
python
from pyqpanda3.visualization import (
InstructionScheduleItem,
parse_instruction_schedule,
parse_instruction_schedules,
draw_time_scheduling,
)InstructionScheduleItem
InstructionScheduleItem 是一个冻结 dataclass，用于表示归一化后的单条指令。
| 字段 | 类型 | 说明 |
|---|---|---|
name | str | 门或标记名称，例如 RPhi、CZ、IDLE 或 Measure。 |
qubits | tuple[int, ...] | 指令流中的物理量子比特编号，尚未应用显示偏移。 |
start_time | int | 开始周期。 |
duration | float | 持续周期。持续时间为 0 时会绘制为标记。 |
params | tuple[float, ...] | 保留下来的门参数，用于检查和合并判断。 |
order | int | 指令在原始流中的索引，用作稳定排序依据。 |
is_marker | bool | 是否绘制为零持续时间标记。 |
end_time | float | 计算属性，等于 start_time + duration。 |
指令 JSON 格式
解析器接受 QProg.to_instruction 生成的指令格式。每条指令都是单键对象：
| 指令 | Payload |
|---|---|
RPhi | [qubit, angle, phi, start_time] |
CZ | [q0, q1, start_time] |
MS | [q0, q1, start_time] |
IDLE | [qubit, duration, start_time] |
ECHO | [qubit, param, start_time] |
Measure | [[q0, q1, ...], start_time] |
单个调度流可以写成 [{...}, {...}]，也可以包裹为 [[{...}, {...}]]。多个调度流必须写成 [[{...}], [{...}]]。
parse_instruction_schedule
python
parse_instruction_schedule(
instruction: str | Sequence,
durations: Mapping[str, float] | None = None,
backend: Any | None = None,
strict: bool = True,
) -> list[InstructionScheduleItem]解析恰好一个指令流。如果输入包含多个指令流，该函数会抛出 ValueError；此时请使用 parse_instruction_schedules。
parse_instruction_schedules
python
parse_instruction_schedules(
instruction: str | Sequence,
durations: Mapping[str, float] | None = None,
backend: Any | None = None,
strict: bool = True,
) -> list[list[InstructionScheduleItem]]接受 [{...}]、[[{...}]] 或 [[{...}], [{...}]]，并为每个指令流返回一个归一化调度列表。
draw_time_scheduling
python
draw_time_scheduling(
instruction,
durations=None,
backend=None,
output="mpl",
qubits=None,
title="QProg Instruction Schedule",
width=None,
height=None,
show_labels=True,
label_policy="auto",
max_qubits_per_panel=None,
time_window=None,
qubit_offset=-1,
merge_common_instructions=False,
gate_filter=None,
filter_measure=False,
time_range=None,
plotly_lane_height=None,
strict=True,
)当 output="mpl" 时返回 Matplotlib Figure，当 output="plotly" 时返回 Plotly Figure。如果输入包含多个指令流，则返回图对象列表。
持续时间来源
持续时间按以下优先级解析：
- 显式传入的
durations，例如{"RPhi": 40, "CZ": 40}。 - 后端时间属性：
single_gate_timing用于RPhi，double_gate_timing用于CZ和MS，echo_gate_timing用于ECHO。 IDLE指令 payload 中的持续时间。- 缺失持续时间的指令会作为零持续时间标记。
示例
python
from pyqpanda3.visualization import parse_instruction_schedule, draw_time_scheduling
instruction = [
{"RPhi": [20, 270.0, 90.0, 0]},
{"RPhi": [29, 270.0, 90.0, 0]},
{"CZ": [20, 29, 40]},
{"RPhi": [29, 72.76854713789294, 90.0, 80]},
{"Measure": [[29, 20], 120]},
]
items = parse_instruction_schedule(instruction, durations={"RPhi": 40, "CZ": 40})
print(items[0].name, items[0].end_time)
# 输出：RPhi 40.0
fig = draw_time_scheduling(
instruction,
durations={"RPhi": 40, "CZ": 40},
title="Two-Qubit Schedule",
)
fig.savefig("schedule.png", dpi=160)
python
from pyqpanda3.visualization import draw_time_scheduling
multi_stream = [
[
{"RPhi": [20, 270.0, 90.0, 0]},
{"RPhi": [29, 270.0, 90.0, 0]},
{"CZ": [20, 29, 40]},
{"RPhi": [29, 72.76854713789294, 90.0, 80]},
{"Measure": [[29, 20], 120]},
],
[
{"RPhi": [20, 270.0, 90.0, 0]},
{"RPhi": [29, 270.0, 90.0, 0]},
{"CZ": [20, 29, 40]},
{"RPhi": [29, 72.76854713789294, 90.0, 80]},
{"Measure": [[29, 20], 120]},
],
]
figures = draw_time_scheduling(
multi_stream,
durations={"RPhi": 40, "CZ": 40},
output="plotly",
qubit_offset=-1,
)
for index, fig in enumerate(figures):
fig.write_html(f"schedule-{index}.html")