Cirq Google 设备规格（DeviceSpecification）完全指南：从 Proto 定义到 GridDevice 电路校验

• 科学计算

设备规格（Device Specification）是 Cirq 描述 Google 量子处理器布局、门集、门时长与耦合关系的核心协议，也是将电路安全提交到真实硬件前进行合法性校验的事实来源。本文以docs/google/specification.md为主线，结合cirq-google子包中的device.proto、GridDevice实现与虚拟引擎模板，系统讲解设备规格的数据结构、门集与目标集语义、时长约定，以及如何把规格转换为可直接校验电路的cirq.Device对象。读完本文，你将能够读懂任意 Google 处理器的规格文件、用几行代码打印全部门的时长、理解 SYMMETRIC 与 PERMUTATION 目标集的区别，并在离线环境下用仓库自带的规格模板完成同样的校验工作。

为什么需要一份"设备规格"

Google 的量子处理器布局并不是千篇一律的。虽然仓库为常用处理器定义了若干标准 Google 设备，但每个具体处理器都可能存在专属的布局细节：例如某个或多个 qubit 因故"掉线"（drop-out）而不可用，或者某些新特性、实验性功能只在部分设备上开放。若把所有这些信息硬编码进客户端代码，将难以跟上硬件的持续演进。

因此 Cirq 用一份协议缓冲（protobuf）规格来描述设备的全部能力，这份规格定义在cirq_google.api.v2命名空间的Deviceproto 中，具体见 device.proto。开发者可以通过Engine实时拉取某个处理器的最新规格，也可以把规格保存为二进制或 TextProto 文件离线使用，从而在不依赖网络的情况下完成电路设计与预校验。

DeviceSpecification 的整体结构

DeviceSpecification消息（见 device.proto）是整份规格的根节点，其字段如下：

注意valid_qubits的约定：单比特门可作用于所有列出的 qubit，测量门和等待门可作用于这些 qubit 的任意子集，而两比特门则必须通过valid_targets中的耦合对来约束。

仓库实际使用的规格模板可以印证这一点，例如 willow_pink_d7v1-2024_08_16_device_spec_for_grid_device.proto.txt 以valid_qubits: "6_0"、"2_4"等网格坐标逐行声明有效 qubit。

在较新版本的GateSpecification中，每个门通过oneof字段指明具体类型，仓库支持的类型包括Sycamore、SqrtISwap、SqrtISwapInv、CZ、PhasedXZ、VirtualZPow、PhysicalZPow、CouplerPulse、Measurement、Wait、FSimViaModel、TwoPulseFSim、CZPowGate、InternalGate、Reset、AnalogDetuneQubit、AnalogDetuneCouplerOnly与WaitGateWithUnit（见 device.proto）。未来新增门类型时，只需为oneof增加新的 message 分支，即可在不破坏既有客户端的条件下扩展。

Gate Set：设备的门集规格

大多数设备只能接受一个受限的门集合，即设备的 gate set。任何提交到该设备的电路，其中出现的门都必须属于该集合。门集部分（GateSet，见 device.proto）定义了设备上哪些门集是合法的，以及每个门集由哪些门组成：

• name：门集名称，对应 Program 中Language.gate_set的取值；
• valid_gates：该门集允许的GateDefinition列表。

GateDefinition：一个门的完整定义

每个门集内的门都由GateDefinition描述（见 device.proto），它声明了门的序列化 id、qubit 数量、参数、时长以及可作用的 qubit：

参数约束由ArgDefinition（见 device.proto）进一步细化：ArgType可取UNSPECIFIED、FLOAT、REPEATED_BOOLEAN、STRING；对于FLOAT类型的参数，还可以通过allowed_ranges给出允许的取值范围。ArgumentRange的语义是最小值包含、最大值不包含，当最小值和最大值相同时，只允许取该单一值（见 device.proto）——这正是为参数化门（如带角度的相位门）表达合法参数区间的机制。

Gate Durations：以皮秒为单位的门时长

设备执行每个门所需的时间被记录在规格中，以**整数皮秒（picoseconds）**存储。文档原示例代码展示了如何遍历设备规格、打印每个门集下所有门及其时长：

import cirq_google # Create an Engine object to use. engine = cirq_google.Engine(project_id=PROJECT_ID) # Replace the processor id to get the device specification with that id. spec = engine.get_processor(PROCESSOR_ID).get_device_specification() # Iterate through each gate set valid on the device. for gateset in spec.valid_gate_sets: print(gateset.name) print('-------') # Prints each gate valid in the set with its duration for gate in gateset.valid_gates: print('%s %d' % (gate.id, gate.gate_duration_picos))

这里PROJECT_ID与PROCESSOR_ID需要替换为实际值（仓库文档示例中使用了PROCESSOR_ID = "willow_pink"）。Engine.get_processor(...).get_device_specification()是AbstractProcessor接口声明的抽象方法（见 abstract_processor.py），其在线实现会从 Quantum Computing Service 拉取处理器当前的规格 proto（见 engine_processor.py）。

两个值得注意的约定：

1. 测量门时长包含两段：按约定，测量门的gate_duration_picos既包含测量 qubit 的"读出脉冲（read-out）"时长，也包含测量谐振器恢复回基态所需的"振铃衰减（ring-down）"时间。
2. 时长会随硬件变化：仓库在 Google 设备文档 中明确提示门时长可能随硬件更新而变化，应以设备规格中的最新数值为准；部分门（如 Z 门、FSim 门）存在多种变体，时长也可能不同。

在实际设备上，一个 moment 的持续时长等于其中最长门的时长，因此把时长相近的门对齐到同一 moment 能缩短电路总时长，详见 best practices。

Target Sets：门作用范围的高效表达

大多数门作用的 qubit 集合是相同的（例如所有两比特门都作用于同一批耦合对）。为了避免为每个门重复列举这些 qubit（或 qubit 对），规格用**目标集（target set）**来集中定义合法作用范围（见 device.proto）。

每个 target set 包含一个name和一组Target列表；一个Target就是一串 qubit id（见 device.proto）：单比特门的一个 target 是单个 qubit，两比特门的一个 target 是一对 qubit。target_ordering决定 target 如何被解释，共有三种类型：

第三种类型典型用于测量门：测量门可以同时作用于任意数量的 qubit，无需为每种组合单独声明。需要说明的是，文档中写作PERMUTATION_SET，而 device.proto 中对应的枚举名是SUBSET_PERMUTATION，且已被标记为 deprecated（新版本中测量门可直接作用于所有合法 qubit 子集，valid_qubits字段注释已给出该约定）。SYMMETRIC是目前两比特门最常用的类型。

Developer Recommendations：软性建议字段

developer_recommendations是一个自由文本字段，用于承载未被硬性规则捕获的补充建议和软性要求。典型内容如"不要连续施加两个 CZ 门"（"Do not apply two CZ gates in a row."）、"所有 Z 门都会被转换为 VirtualZ 门"（见 device.proto 注释示例）。这类建议属于最佳实践层面，与硬性校验规则（门集、qubit 合法性）是分开的。

转换为 cirq.Device：用 GridDevice 校验电路

规格本身是 protobuf，而 Cirq 用户更常用的是核心cirq.Device抽象。cirq_google.GridDevice类（见 grid_device.py）正是二者的桥梁：它实现了cirq.Device接口，将规格中的信息封装进metadata属性，并可用于校验电路、moment 与操作。

文档给出的在线校验示例：

import cirq import cirq_google # Create an Engine object to use. engine = cirq_google.Engine(project_id=PROJECT_ID) # Replace the processor id to get the device with that id. device = engine.get_processor(PROCESSOR_ID).get_device() q0 = cirq.GridQubit(6, 6) q1 = cirq.GridQubit(6, 7) circuit = cirq.Circuit(cirq.CNOT(q0, q1)) # raises ValueError device.validate_circuit(circuit)

这段代码中，get_device()在AbstractProcessor上被定义为"查询处理器规格并据此构造一个用于校验的Device"（见 abstract_processor.py）；EngineProcessor的实现会先取回规格 proto，再调用GridDevice.from_proto(spec)完成转换（见 engine_processor.py）。示例中的 CNOT 门不在 Google 设备的原生门集内，因此validate_circuit会抛出ValueError。

GridDevice.from_proto()在转换时会执行严格校验（见 grid_device.py），以下情况会被判定为非法规格并抛出ValueError：

• valid_qubits中的字符串不是<int>_<int>形式，无法解析为cirq.GridQubit；
• valid_targets引用了不在valid_qubits中的 qubit；
• SYMMETRIC类型的 target set 含有重复 qubit 的 target（例如自环的 qubit 对）。

转换完成后，GridDevice.metadata提供了一组可直接使用的视图（见 grid_device.py）：qubit_set（有效 qubit 集合）、qubit_pairs（两比特门可作用的耦合对）、isolated_qubits（不参与任何耦合对的孤立 qubit）、gateset（设备支持的门集）、gate_durations（每个门的近似时长映射）以及compilation_target_gatesets（可用于把电路变换到原生目标门集的编译目标）。这一行为在测试中得到验证：test_grid_device_from_proto断言了 qubit 集合、耦合对、门集与时长映射的一致性（见 grid_device_test.py），而test_grid_device_validate_operations_positive等用例确认了单比特门、水平/垂直耦合对、以及任意子集上的测量与 WaitGate 均可通过validate_operation（见 grid_device_test.py）。

离线保存与复用规格

如果不想依赖网络流量，DeviceSpecification可以很方便地以二进制格式（SerializeToString）或 TextProto 格式（TextFormat.PrintToString）保存到本地，后续再反序列化并交给GridDevice.from_proto()使用。仓库的 specifications 目录 本身就是这种实践的范例，其中存放了rainbow、weber、willow_pink等处理器的 TextProto 规格模板。

离线实验：用虚拟引擎与模板规格替代在线调用

文档中的示例代码都假设可以联网调用cirq_google.Engine。若希望完全离线复现上述流程，可以使用virtual_engine_factory提供的模板机制：MOST_RECENT_TEMPLATES将处理器 id 映射到规格模板文件名（见 virtual_engine_factory.py），目前包含rainbow、weber与willow_pink。例如，将文档示例中的 Engine 调用替换为：

from cirq_google.engine import virtual_engine_factory as factory # 直接基于模板构造一个 GridDevice（无网络依赖） device = factory.create_device_from_processor_id("willow_pink") # 或构造一个包含全部最新模板的虚拟引擎 engine = factory.create_noiseless_virtual_engine_from_latest_templates() spec = engine.get_processor("willow_pink").get_device_specification()

create_device_from_processor_id会读取模板并调用GridDevice.from_proto（见 virtual_engine_factory.py）；create_noiseless_virtual_engine_from_latest_templates则把所有最新模板组装成一个模拟 Quantum Computing Service 的本地引擎（见 virtual_engine_factory.py）。仓库还预定义了常用设备常量，如Willow105 = engine.create_device_from_processor_id('willow_pink')（见 known_devices.py），可直接用于本地开发与测试。需要注意的是，create_noiseless_virtual_engine_from_latest_templates的处理器集合随硬件演进而变化，跨版本不保证向后兼容。

小结

设备规格是 Cirq 与 Google 量子硬件之间的"契约文件"：DeviceSpecificationproto 以门集、目标集、门时长和 qubit 清单描述一台处理器的能力边界；GridDevice.from_proto()将其转换为cirq.Device，从而让validate_circuit/validate_operation在提交前拦截非法电路。掌握这份规格，你既能读懂任意处理器的原始布局与门约束，也能借助仓库自带的 TextProto 模板在离线环境中完成完整的设备感知开发与校验流程。

• 科学计算