科学计算【免费下载链接】CirqPython framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.项目地址https://gitcode.com/gh_mirrors/ci/Cirq点击查看免费下载本文是 Cirq 官方 IonQ 接入文档docs/hardware/ionq/service.md的深度实践指南面向需要在真实量子硬件或云端模拟器上执行量子线路的开发者。文章围绕cirq_ionq.Service这一核心入口完整覆盖从 API Key 认证、阻塞式运行线路、结果解析到 Service 与 run 方法全部配置参数的实战用法并结合cirq-ionq包的源码service.py、ionq_client.py 等说明底层调用与重试机制。读完本文你将能够独立配置 IonQ API 服务、提交线路任务、读取并转换测量结果并理解阻塞轮询与错误缓解error mitigation的内部原理。IonQ API 服务概览IonQ 的 API 提供了一条在 IonQ 离子阱trapped ion量子计算机以及云端模拟器上执行量子线路的通道。使用该服务的前提是拥有一个 IonQ 账户并获取 API Key注册与申请方式可参考官方入门页面而在 Cirq 仓库中docs/hardware/ionq/access.md 详细介绍了获取与配置 API Key 的方法。在 Cirq 中访问 IonQ API 的主入口是cirq_ionq.Service类的实例。该对象必须使用 API Key 完成初始化也可以借助环境变量之后它便承担了与 IonQ API 交互的全部职责提交线路、轮询任务状态、获取结果、查询设备校准数据等。快速上手以阻塞方式运行一个量子线路在 IonQ 服务上以阻塞blocking方式运行量子线路共分四个基本步骤创建线路circuit用 Cirq 构造要运行的量子线路创建cirq_ionq.Service提供正确的认证信息与端点提交并等待结果调用run将线路提交到服务并等待该调用返回结果也可以改用异步 Job 与后续处理方式转换结果把返回结果整理成最便于分析的形式。下面的完整示例演示了这一流程线路对单个量子比特施加“根号非门”square root of NOT后进行测量共执行 100 次重复repetitions目标后端为qpuimport cirq import cirq_ionq as ionq # A circuit that applies a square root of NOT and then a measurement. qubit cirq.LineQubit(0) circuit cirq.Circuit( cirq.X(qubit) ** 0.5, # Square root of NOT. cirq.measure(qubit, keyx), # Measurement store in key x ) # Create a ionq.Service object. # Replace API_KEY with your API key. # Alternatively, if you have the IONQ_API_KEY environment # variable set, you can omit specifying this api_key parameters. service ionq.Service(api_keyAPI_KEY) # Run a program against the service. This method will block execution until # the result is returned (determined by periodically polling the IonQ API). result service.run(circuitcircuit, repetitions100, targetqpu) # The return object of run is a cirq.Result object. # From this object, you can get a histogram of results. histogram result.histogram(keyx) print(fHistogram: {histogram}) # You can also get the data as a pandas frame. print(fData:\n{result.data})由于量子测量存在随机性实际输出会有所浮动典型输出如下Histogram: Counter({0: 53, 1: 47}) Data: x 0 0 1 0 2 0 3 0 4 0 .. .. 95 1 96 1 97 1 98 1 99 1 [100 rows x 1 columns]可以看到run返回的是标准的cirq.Result对象result.histogram(keyx)给出以测量键x聚合的计数直方图Counterresult.data则返回 pandas DataFrame 形式的原始测量数据。上述示例的代码同样被仓库的 doctest 机制覆盖验证相关测试替换逻辑记录在 service.md 源文件中。结果顺序的一个注意事项使用run获取的结果中测量位串的顺序并不对应线路执行的时间顺序。IonQ API 返回的是结果的统计信息即 0 与 1 各自出现的计数Cirq 为了兼容自身的cirq.Result表示会将统计结果按字典序展开为恰好相同数量的原始结果。因此如果你看到类似“前面全是 0、后面全是 1”的排列这不是量子随机性的异常而是 API 统计结果展开后的必然形态。Service 构造参数详解除了api_keycirq_ionq.Service还提供若干用于配置服务的参数全部在构造对象时以关键字参数传入。下表汇总了各参数的语义与 service.py 中的构造函数签名一一对应参数含义与默认行为api_key访问 API 的密钥。若为None则依次读取环境变量CIRQ_IONQ_API_KEY、IONQ_API_KEY若均未设置构造时抛出EnvironmentError见 service.pyremote_hostAPI 服务地址URL 形式。若为None则依次读取环境变量CIRQ_IONQ_REMOTE_HOST、IONQ_REMOTE_HOST若均未设置则使用默认值https://api.ionq.co/{api_version}default_target默认运行目标取值为simulator或qpu。设置后使用run、create_job或 sampler 接口提交任务时无需每次指定 target推荐的实践是分别创建两个 Service一个默认跑模拟器、一个默认跑 QPUapi_version使用的 API 版本默认v0.4max_retry_secondsAPI 轮询采用指数退避exponential backoff重试此参数控制重试在多少秒后放弃。需要“快速失败”时可设为很小的值长任务可设很大的值job_settings一个字典可覆盖线路在 IonQ 硬件上运行时的行为设置默认{}verbose是否在遇到可重试错误时向 stderr/stdout 打印信息默认False其中job_settings与verbose两个参数虽未出现在官方入门文档中但在当前仓库的 service.py 中已实现job_settings会被透传给序列化器serializer.Serializer而verbose会传递给底层的_IonQClient用于打印重试错误信息。环境变量与参数优先级从源码可以确认一套明确的取值优先级规则service.pyremote_host显式参数 →CIRQ_IONQ_REMOTE_HOST→IONQ_REMOTE_HOST→ 默认https://api.ionq.co/{api_version}api_key显式参数 →CIRQ_IONQ_API_KEY→IONQ_API_KEY→ 抛错。仓库测试 service_test.py 中test_service_api_key_via_env、test_service_remote_host_via_env、test_service_api_key_from_env_var_cirq_ionq_precedence等用例对上述规则进行了逐一验证。因此最简单的初始化方式是在 shell 中设置环境变量后直接ionq.Service()export IONQ_API_KEYtomyheartimport cirq_ionq as ionq service ionq.Service()把密钥存放在环境变量而非源码中可以避免密钥被意外提交到版本控制系统而泄露。run 方法参数详解调用run提交任务时可以提供的参数如下与 service.py 的run签名一致circuit要运行的cirq.Circuit。repetitions线路重复运行采样的次数。name为创建的 Job 指定一个名称可选注意它不同于服务器分配的job_id。target任务运行位置取值为qpu或simulator。param_resolver一个cirq.ParamResolver用于解析线路中的参数。run内部会先调用cirq.resolve_parameters(circuit, param_resolver)完成参数替换再进行任务提交。seed仅对simulation任务有效用于指定模拟采样的随机种子。若为None使用np.random若为整数使用np.random.RandomState(int)否则必须传入一个行为类似np.random的随机数对象。error_mitigation错误缓解设置的字典。有效键为debias设为True开启 debiasing可去除特定量子比特噪声从而改善线路性能在 Aria 系列系统上 debiasing 默认开启。值得注意的是源码 docstringservice.py记录的键名为debiasing而官方入门文档示例使用debias具体以你所使用的 API 版本接受的设置为准。sharpen从 debiasing 结果中获取“锐化”sharpened结果默认关闭。若你的期望输出分布存在明显的峰值开启后通常能得到更准确的结果。extra_query_params指定要附加到请求中的额外参数字典当前暂未使用。此外源码还实现了以下在入门文档中未展开、但实际可用的参数见 service.pycompilation线路编译设置默认值为{opt: 0, precision: 1E-3}。noise噪声模型设置格式为{model: str (必填), seed: int (可选)}可用的模型包括ideal、aria-1、aria-2、forte-1、forte-enterprise-1。metadata附加到 Job 上的可选元数据字典。dry_run若为TrueJob 会被 API 客户端提交但不在远端实际处理可用于获取成本估算simulator目标上该选项无效ionq_client.py 会发出警告。使用错误缓解与锐化的示例# Run a program against the service with error mitigation and sharpening result service.run( circuitcircuit, repetitions100, targetqpu, error_mitigation{debias: True}, sharpenTrue, )run方法返回cirq.Result对象从中可获取结果直方图等统计信息处理方式与上文第一个示例一致。阻塞运行背后的机制轮询与指数退避重试run之所以能够“阻塞直到结果返回”是因为底层_IonQClient会在创建 Job 后持续轮询 API。了解这一机制有助于合理设置max_retry_secondsrun首先通过create_job创建任务随后调用job.results()轮询任务状态直至进入终止状态completed、canceled、failed、deleted等定义见 job.py_IonQClient._make_request实现了带指数退避的重试初始退避间隔为 0.1 秒每次失败后翻倍delay_seconds * 2当累计退避时间超过max_retry_seconds时抛出TimeoutErrorionq_client.py可重试的 HTTP 状态码包括 429、500、502、503 以及 520–529 等GET 请求额外将 409 视为可重试ionq_client.py认证通过请求头Authorization: apiKey key完成User-Agent 形如cirq/version (python/version)ionq_client.py客户端仅接受qpu与simulator两个目标仅支持 API 版本v0.4ionq_client.py构造时会对这些取值做断言校验。因此当你希望任务快速失败时可将max_retry_seconds设为很小的值而对于队列较长、耗时较久的 QPU 任务则应将其调大避免轮询提前放弃。深入理解返回结果run始终返回单个cirq.Result这是它相较于直接操作 Job 更方便的地方。若你使用create_job直接管理任务则job.results()的返回类型取决于输入单线路 Job 返回单个ionq.QPUResult或ionq.SimulatorResult批量 Job 返回这些结果的列表详见 docs/hardware/ionq/jobs.md。其中QPUResult内部保存计数统计countsto_cirq_result会将其展开为cirq.ResultSimulatorResult保存的是各结果的概率分布to_cirq_result会依据概率分布与seed现场采样生成cirq.Resultresults.py。仓库测试 service_test.py 对run在qpu与simulator两种目标下的结果转换均有覆盖可作为理解返回值的参考。下一步接入 Service 只是起点Cirq 仓库的 IonQ 文档还提供了三条进阶路径Learn how to build circuits for the API了解 IonQ API 支持的量子比特类型cirq.LineQubit、原生门集以及如何用cirq.optimize_for_target_gatesetcirq_ionq.IonQTargetGateset把普通线路编译到 API 门集How to use the service API掌握run、sampler、create_job三种任务提交方式以及 Job 的取消、删除与结果轮询Get information about QPUs from IonQ calibrations通过service.get_current_calibration()获取设备保真度、门时序、连通性等校准信息用于线路设计前的设备评估。如果你想深入阅读实现细节可以继续探索以下源码文件service.pyService 全量 API、ionq_client.pyREST 请求、重试与认证、job.pyJob 状态机与结果轮询、results.pyQPU/模拟器结果类型、serializer.py线路序列化与门集判定以及 sampler.pysampler 接口实现。赞分享科学计算【免费下载链接】CirqPython framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.项目地址https://gitcode.com/gh_mirrors/ci/Cirq点击查看免费下载相关推荐Cirq-AQT 集成模块实战在 Alpine Quantum Technologies 离子阱量子计算机上运行 Cirq 电路Cirq AQT 集成模块实战在 Alpine Quantum Technologies 离子阱量子计算机上运行 Cirq 电路 本文是 Cirq 官方集成模科学计算深入 Cirq-Pasqal 集成模块在 Pasqal 中性原子量子计算机上运行 Cirq 电路深入 Cirq Pasqal 集成模块在 Pasqal 中性原子量子计算机上运行 Cirq 电路 导读 Cirq Pasqal cirq pasqal 是科学计算Cirq 集成 IonQ 量子计算机cirq-ionq 模块安装、认证与任务提交实战Cirq 集成 IonQ 量子计算机cirq ionq 模块安装、认证与任务提交实战 cirq ionq 是 Cirq 生态中连接 IonQ 离子阱量子计算机科学计算上一篇如何5分钟快速掌握PS4金手指管理器GoldHEN终极完整指南下一篇Path of Building PoE2流放之路2玩家的终极构建规划神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 11:54:37 · 阅读 1.2k 使用 Cirq 的 cirq_ionq.Service 在 IonQ 离子阱量子计算机与云端模拟器上运行量子线路
科学计算【免费下载链接】CirqPython framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.项目地址https://gitcode.com/gh_mirrors/ci/Cirq点击查看免费下载本文是 Cirq 官方 IonQ 接入文档docs/hardware/ionq/service.md的深度实践指南面向需要在真实量子硬件或云端模拟器上执行量子线路的开发者。文章围绕cirq_ionq.Service这一核心入口完整覆盖从 API Key 认证、阻塞式运行线路、结果解析到 Service 与 run 方法全部配置参数的实战用法并结合cirq-ionq包的源码service.py、ionq_client.py 等说明底层调用与重试机制。读完本文你将能够独立配置 IonQ API 服务、提交线路任务、读取并转换测量结果并理解阻塞轮询与错误缓解error mitigation的内部原理。IonQ API 服务概览IonQ 的 API 提供了一条在 IonQ 离子阱trapped ion量子计算机以及云端模拟器上执行量子线路的通道。使用该服务的前提是拥有一个 IonQ 账户并获取 API Key注册与申请方式可参考官方入门页面而在 Cirq 仓库中docs/hardware/ionq/access.md 详细介绍了获取与配置 API Key 的方法。在 Cirq 中访问 IonQ API 的主入口是cirq_ionq.Service类的实例。该对象必须使用 API Key 完成初始化也可以借助环境变量之后它便承担了与 IonQ API 交互的全部职责提交线路、轮询任务状态、获取结果、查询设备校准数据等。快速上手以阻塞方式运行一个量子线路在 IonQ 服务上以阻塞blocking方式运行量子线路共分四个基本步骤创建线路circuit用 Cirq 构造要运行的量子线路创建cirq_ionq.Service提供正确的认证信息与端点提交并等待结果调用run将线路提交到服务并等待该调用返回结果也可以改用异步 Job 与后续处理方式转换结果把返回结果整理成最便于分析的形式。下面的完整示例演示了这一流程线路对单个量子比特施加“根号非门”square root of NOT后进行测量共执行 100 次重复repetitions目标后端为qpuimport cirq import cirq_ionq as ionq # A circuit that applies a square root of NOT and then a measurement. qubit cirq.LineQubit(0) circuit cirq.Circuit( cirq.X(qubit) ** 0.5, # Square root of NOT. cirq.measure(qubit, keyx), # Measurement store in key x ) # Create a ionq.Service object. # Replace API_KEY with your API key. # Alternatively, if you have the IONQ_API_KEY environment # variable set, you can omit specifying this api_key parameters. service ionq.Service(api_keyAPI_KEY) # Run a program against the service. This method will block execution until # the result is returned (determined by periodically polling the IonQ API). result service.run(circuitcircuit, repetitions100, targetqpu) # The return object of run is a cirq.Result object. # From this object, you can get a histogram of results. histogram result.histogram(keyx) print(fHistogram: {histogram}) # You can also get the data as a pandas frame. print(fData:\n{result.data})由于量子测量存在随机性实际输出会有所浮动典型输出如下Histogram: Counter({0: 53, 1: 47}) Data: x 0 0 1 0 2 0 3 0 4 0 .. .. 95 1 96 1 97 1 98 1 99 1 [100 rows x 1 columns]可以看到run返回的是标准的cirq.Result对象result.histogram(keyx)给出以测量键x聚合的计数直方图Counterresult.data则返回 pandas DataFrame 形式的原始测量数据。上述示例的代码同样被仓库的 doctest 机制覆盖验证相关测试替换逻辑记录在 service.md 源文件中。结果顺序的一个注意事项使用run获取的结果中测量位串的顺序并不对应线路执行的时间顺序。IonQ API 返回的是结果的统计信息即 0 与 1 各自出现的计数Cirq 为了兼容自身的cirq.Result表示会将统计结果按字典序展开为恰好相同数量的原始结果。因此如果你看到类似“前面全是 0、后面全是 1”的排列这不是量子随机性的异常而是 API 统计结果展开后的必然形态。Service 构造参数详解除了api_keycirq_ionq.Service还提供若干用于配置服务的参数全部在构造对象时以关键字参数传入。下表汇总了各参数的语义与 service.py 中的构造函数签名一一对应参数含义与默认行为api_key访问 API 的密钥。若为None则依次读取环境变量CIRQ_IONQ_API_KEY、IONQ_API_KEY若均未设置构造时抛出EnvironmentError见 service.pyremote_hostAPI 服务地址URL 形式。若为None则依次读取环境变量CIRQ_IONQ_REMOTE_HOST、IONQ_REMOTE_HOST若均未设置则使用默认值https://api.ionq.co/{api_version}default_target默认运行目标取值为simulator或qpu。设置后使用run、create_job或 sampler 接口提交任务时无需每次指定 target推荐的实践是分别创建两个 Service一个默认跑模拟器、一个默认跑 QPUapi_version使用的 API 版本默认v0.4max_retry_secondsAPI 轮询采用指数退避exponential backoff重试此参数控制重试在多少秒后放弃。需要“快速失败”时可设为很小的值长任务可设很大的值job_settings一个字典可覆盖线路在 IonQ 硬件上运行时的行为设置默认{}verbose是否在遇到可重试错误时向 stderr/stdout 打印信息默认False其中job_settings与verbose两个参数虽未出现在官方入门文档中但在当前仓库的 service.py 中已实现job_settings会被透传给序列化器serializer.Serializer而verbose会传递给底层的_IonQClient用于打印重试错误信息。环境变量与参数优先级从源码可以确认一套明确的取值优先级规则service.pyremote_host显式参数 →CIRQ_IONQ_REMOTE_HOST→IONQ_REMOTE_HOST→ 默认https://api.ionq.co/{api_version}api_key显式参数 →CIRQ_IONQ_API_KEY→IONQ_API_KEY→ 抛错。仓库测试 service_test.py 中test_service_api_key_via_env、test_service_remote_host_via_env、test_service_api_key_from_env_var_cirq_ionq_precedence等用例对上述规则进行了逐一验证。因此最简单的初始化方式是在 shell 中设置环境变量后直接ionq.Service()export IONQ_API_KEYtomyheartimport cirq_ionq as ionq service ionq.Service()把密钥存放在环境变量而非源码中可以避免密钥被意外提交到版本控制系统而泄露。run 方法参数详解调用run提交任务时可以提供的参数如下与 service.py 的run签名一致circuit要运行的cirq.Circuit。repetitions线路重复运行采样的次数。name为创建的 Job 指定一个名称可选注意它不同于服务器分配的job_id。target任务运行位置取值为qpu或simulator。param_resolver一个cirq.ParamResolver用于解析线路中的参数。run内部会先调用cirq.resolve_parameters(circuit, param_resolver)完成参数替换再进行任务提交。seed仅对simulation任务有效用于指定模拟采样的随机种子。若为None使用np.random若为整数使用np.random.RandomState(int)否则必须传入一个行为类似np.random的随机数对象。error_mitigation错误缓解设置的字典。有效键为debias设为True开启 debiasing可去除特定量子比特噪声从而改善线路性能在 Aria 系列系统上 debiasing 默认开启。值得注意的是源码 docstringservice.py记录的键名为debiasing而官方入门文档示例使用debias具体以你所使用的 API 版本接受的设置为准。sharpen从 debiasing 结果中获取“锐化”sharpened结果默认关闭。若你的期望输出分布存在明显的峰值开启后通常能得到更准确的结果。extra_query_params指定要附加到请求中的额外参数字典当前暂未使用。此外源码还实现了以下在入门文档中未展开、但实际可用的参数见 service.pycompilation线路编译设置默认值为{opt: 0, precision: 1E-3}。noise噪声模型设置格式为{model: str (必填), seed: int (可选)}可用的模型包括ideal、aria-1、aria-2、forte-1、forte-enterprise-1。metadata附加到 Job 上的可选元数据字典。dry_run若为TrueJob 会被 API 客户端提交但不在远端实际处理可用于获取成本估算simulator目标上该选项无效ionq_client.py 会发出警告。使用错误缓解与锐化的示例# Run a program against the service with error mitigation and sharpening result service.run( circuitcircuit, repetitions100, targetqpu, error_mitigation{debias: True}, sharpenTrue, )run方法返回cirq.Result对象从中可获取结果直方图等统计信息处理方式与上文第一个示例一致。阻塞运行背后的机制轮询与指数退避重试run之所以能够“阻塞直到结果返回”是因为底层_IonQClient会在创建 Job 后持续轮询 API。了解这一机制有助于合理设置max_retry_secondsrun首先通过create_job创建任务随后调用job.results()轮询任务状态直至进入终止状态completed、canceled、failed、deleted等定义见 job.py_IonQClient._make_request实现了带指数退避的重试初始退避间隔为 0.1 秒每次失败后翻倍delay_seconds * 2当累计退避时间超过max_retry_seconds时抛出TimeoutErrorionq_client.py可重试的 HTTP 状态码包括 429、500、502、503 以及 520–529 等GET 请求额外将 409 视为可重试ionq_client.py认证通过请求头Authorization: apiKey key完成User-Agent 形如cirq/version (python/version)ionq_client.py客户端仅接受qpu与simulator两个目标仅支持 API 版本v0.4ionq_client.py构造时会对这些取值做断言校验。因此当你希望任务快速失败时可将max_retry_seconds设为很小的值而对于队列较长、耗时较久的 QPU 任务则应将其调大避免轮询提前放弃。深入理解返回结果run始终返回单个cirq.Result这是它相较于直接操作 Job 更方便的地方。若你使用create_job直接管理任务则job.results()的返回类型取决于输入单线路 Job 返回单个ionq.QPUResult或ionq.SimulatorResult批量 Job 返回这些结果的列表详见 docs/hardware/ionq/jobs.md。其中QPUResult内部保存计数统计countsto_cirq_result会将其展开为cirq.ResultSimulatorResult保存的是各结果的概率分布to_cirq_result会依据概率分布与seed现场采样生成cirq.Resultresults.py。仓库测试 service_test.py 对run在qpu与simulator两种目标下的结果转换均有覆盖可作为理解返回值的参考。下一步接入 Service 只是起点Cirq 仓库的 IonQ 文档还提供了三条进阶路径Learn how to build circuits for the API了解 IonQ API 支持的量子比特类型cirq.LineQubit、原生门集以及如何用cirq.optimize_for_target_gatesetcirq_ionq.IonQTargetGateset把普通线路编译到 API 门集How to use the service API掌握run、sampler、create_job三种任务提交方式以及 Job 的取消、删除与结果轮询Get information about QPUs from IonQ calibrations通过service.get_current_calibration()获取设备保真度、门时序、连通性等校准信息用于线路设计前的设备评估。如果你想深入阅读实现细节可以继续探索以下源码文件service.pyService 全量 API、ionq_client.pyREST 请求、重试与认证、job.pyJob 状态机与结果轮询、results.pyQPU/模拟器结果类型、serializer.py线路序列化与门集判定以及 sampler.pysampler 接口实现。赞分享科学计算【免费下载链接】CirqPython framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.项目地址https://gitcode.com/gh_mirrors/ci/Cirq点击查看免费下载相关推荐Cirq-AQT 集成模块实战在 Alpine Quantum Technologies 离子阱量子计算机上运行 Cirq 电路Cirq AQT 集成模块实战在 Alpine Quantum Technologies 离子阱量子计算机上运行 Cirq 电路 本文是 Cirq 官方集成模科学计算深入 Cirq-Pasqal 集成模块在 Pasqal 中性原子量子计算机上运行 Cirq 电路深入 Cirq Pasqal 集成模块在 Pasqal 中性原子量子计算机上运行 Cirq 电路 导读 Cirq Pasqal cirq pasqal 是科学计算Cirq 集成 IonQ 量子计算机cirq-ionq 模块安装、认证与任务提交实战Cirq 集成 IonQ 量子计算机cirq ionq 模块安装、认证与任务提交实战 cirq ionq 是 Cirq 生态中连接 IonQ 离子阱量子计算机科学计算上一篇如何5分钟快速掌握PS4金手指管理器GoldHEN终极完整指南下一篇Path of Building PoE2流放之路2玩家的终极构建规划神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考