# API 参考

按模块查找 QuantumFerry SDK 的类、方法和返回对象。每个接口列出调用签名、参数默认值、返回类型与源码位置；入门流程和可运行实验仍在相应教程中。签名中的 * 表示后续参数按名称传入，/ 表示前面的参数按位置传入。

| 模块 | 主要对象 | 用途 |
| --- | --- | --- |
| quantum_source_sdk | SchedulerClient、ManagementClient、JobSubmissionConfig | 连接平台、查询目录、准备报价、提交和查询任务。 |
| quantum_source_sdk.backends | BackendCapabilities、GateSpec、Topology | 读取设备接受的线路、门集、拓扑和可配置项。 |
| quantum_source_qiskit | QuantumSourceService、QuantumSourceBackend、SamplerV2、EstimatorV2 | 使用 QuantumCircuit、Target 与 Qiskit 原生结果。 |
| quantum_source_pennylane | QuantumSourceDevice、PreparedPennyLaneBatch | 使用 QNode / QuantumScript 并还原 PennyLane 测量结果。 |

- [Core 与认证](#core)
- [设备能力](#capabilities)
- [Qiskit](#qiskit)
- [PennyLane](#pennylane)
- [底层协议](#protocol)
- [实现与验证索引](#evidence)

## quantum_source_sdk · 连接与任务

### quantum_source_sdk.ClientCredentials

```text
class ClientCredentials(client_id: str, client_secret: str)
```

保存平台 Client ID 与 Client Secret，供客户端凭据认证使用。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| client_id | str | 平台分配的客户端标识。 |
| client_secret | str | 与该标识配套的凭据。 |

返回：ClientCredentials。

源码：sdk/src/quantum_source_sdk/auth.py

### quantum_source_sdk.credentials_from_environment

```text
credentials_from_environment() -> ClientCredentials
```

优先读取 QUANTUM_SOURCE_SDK_KEY 指定的 SDK Key 文件；省略该变量时读取 QUANTUM_SOURCE_CLIENT_ID 与 QUANTUM_SOURCE_CLIENT_SECRET。

返回：ClientCredentials；缺少有效配置时抛出 ValueError。

源码：sdk/src/quantum_source_sdk/auth.py

### quantum_source_sdk.load_credentials_from_file

```text
load_credentials_from_file(path: str | os.PathLike[str]) -> ClientCredentials
```

从平台 SDK Key 文件加载凭据。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| path | str \| PathLike[str] | 本地 SDK Key 文件路径。 |

返回：ClientCredentials。

源码：sdk/src/quantum_source_sdk/auth.py

### quantum_source_sdk.BaseClient

```text
class BaseClient(base_url: str | None = None, *, token: str | None = None, auth: ClientCredentialsAuth | None = None, creds: ClientCredentials | None = None, request_timeout_seconds: float = 30.0, poll_interval_seconds: float = 2.0, wait_timeout_seconds: float = 1800.0, max_response_bytes: int = 2 * 1024 * 1024, _shared_api: ApiTransport | None = None)
```

ManagementClient 与 SchedulerClient 共用的连接配置。通常直接创建这两个业务客户端；连接也支持 with 上下文。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| base_url | str \| None = None | 平台 API 根地址，省略时读取 QUANTUM_SOURCE_API_URL 或 SDK 默认地址。 |
| token / auth / creds | 可选认证对象 | 选择一种显式认证方式；省略时从环境加载凭据。 |
| request_timeout_seconds | float = 30.0 | 单次 HTTP 请求超时秒数。 |
| poll_interval_seconds / wait_timeout_seconds | float = 2.0 / 1800.0 | 默认轮询间隔和等待上限。 |
| max_response_bytes | int = 2097152 | 普通 JSON 响应大小上限。 |
| _shared_api | ApiTransport \| None = None | SDK 内部共享连接入口；常规调用保持默认。 |

返回：BaseClient。close() 释放本地连接。

源码：sdk/src/quantum_source_sdk/clients.py

## 客户端级钱包选择

创建客户端时用 currency 选择 OPEN 或 FULL。新准备请求采用该钱包；切换钱包时使用相应客户端准备新报价，已有准备和已接受任务保留原报价。

### quantum_source_sdk.SchedulerClient

```text
class SchedulerClient(base_url: str | None = None, *, token: str | None = None, auth: ClientCredentialsAuth | None = None, creds: ClientCredentials | None = None, management_client: ManagementClient | None = None, approval_callback: Callable[[JobPreparationResultResponse], bool] | None = None, currency: str = "OPEN", **client_options: Any)
```

高层任务操作入口。currency 选择 OPEN 或 FULL 钱包，默认 OPEN；新准备请求采用当前客户端的钱包。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| currency | str = "OPEN" | OPEN / FULL 分别记账。更换钱包时创建相应客户端，再为新实验准备报价；已有报价继续使用准备时的币种。 |
| management_client | ManagementClient \| None = None | 复用目录客户端；省略时由 SchedulerClient 创建 management 属性。 |
| approval_callback | Callable \| None = None | 直接提交且需要审价时，接收准备结果并返回是否同意。 |
| **client_options | Any | BaseClient 的请求超时、轮询和等待配置。 |

返回：SchedulerClient；management 用于目录查询，currency 为当前钱包。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.ManagementClient

```text
class ManagementClient(base_url: str | None = None, **options: Any)
```

读取组织、厂商、设备目录和账户余额。也可通过 scheduler.management 使用。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| base_url | str \| None = None | 平台 API 根地址。 |
| **options | Any | BaseClient 的认证与连接配置。 |

返回：ManagementClient。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.ManagementClient.list_user_organizations

```text
list_user_organizations(limit: int = 20, cursor: str | None = None) -> PaginatedOrganizations
```

读取当前账号可用组织。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| limit | int = 20 | 每页条数。 |
| cursor | str \| None = None | 第一页省略；后续使用上一页 pagination.next_cursor。 |

返回：PaginatedOrganizations；条目位于 organizations，翻页信息位于 pagination。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.ManagementClient.list_providers

```text
list_providers(limit: int = 20, cursor: str | None = None) -> PaginatedProviders
```

读取厂商目录。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| limit | int = 20 | 每页条数。 |
| cursor | str \| None = None | 第一页省略；后续使用上一页 pagination.next_cursor。 |

返回：PaginatedProviders；条目位于 providers。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.ManagementClient.list_backend_classes

```text
list_backend_classes(limit: int = 20, cursor: str | None = None, provider_id: str | None = None) -> PaginatedBackendClasses
```

读取分页设备目录。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| limit | int = 20 | 每页条数。 |
| cursor | str \| None = None | 第一页省略；后续使用上一页 pagination.next_cursor。 |
| provider_id | str \| None = None | 按厂商标识筛选。 |

返回：PaginatedBackendClasses；设备位于 backend_classes，下一页游标位于 pagination.next_cursor。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.ManagementClient.get_credit_balance

```text
get_credit_balance(organization_id: str) -> CreditBalanceRead
```

读取平台返回的余额与钱包摘要。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| organization_id | str | 当前使用的组织 ID。 |

返回：CreditBalanceRead；wallets 中各 CreditWalletRead 提供 currency、balance、reserved、available 与有效期。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.get_backend_class

```text
get_backend_class(identifier: str) -> BackendClassRead
```

读取一个设备的完整记录。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| identifier | str | 设备 ID 或目录中的 short_code。 |

返回：BackendClassRead，包含 configuration_schema 和能力元数据。

源码：sdk/src/quantum_source_sdk/clients.py

## 任务配置与准备

### quantum_source_sdk.JobSubmissionConfig

```text
class JobSubmissionConfig(backend_class_id: str, name: str, job_subcategory_id: str = "oth:oth", shots: int | None = None, organization_id: str | None = None, configuration_data: Mapping[str, Any] | None = None, execution_plan: str = "public", queue_priority: str = "stand", auto_approve_quote: bool = True, verbose: bool = False, job_timeout_seconds: float = 86400.0, submitted_with: str = "sdk", input_format: str | None = None, provider: str | None = None)
```

一条高层 OpenQASM 任务的不可变配置。configuration_data 使用扁平字典，字段来自所选设备的 configuration_schema。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| backend_class_id / name | str / str；必填 | 目标设备标识和实验名称。 |
| shots | int \| None = None | 采样次数，推荐显式填写正整数；也可从 configuration_data["shots"] 取得，两处同时填写时保持一致。 |
| organization_id | str \| None = None | 组织 ID；省略时由客户端解析可用组织。 |
| configuration_data | Mapping[str, Any] \| None = None | 设备声明的选项，例如 mapping、optimization、amend。 |
| execution_plan / queue_priority | str = "public" / "stand" | 执行方案和队列等级。 |
| auto_approve_quote / verbose | bool = True / False | 直接提交时的审价策略，以及等待进度显示。 |
| job_timeout_seconds | float = 86400.0 | 执行流程等待上限，单位秒。 |
| job_subcategory_id / submitted_with | str = "oth:oth" / "sdk" | 任务分类和提交来源标记。 |
| input_format | str \| None = None | OpenQASM 输入版本；明确版本时填写 openqasm2 或 openqasm3。 |
| provider | str \| None = None | 可选厂商标识。 |

返回：JobSubmissionConfig；effective_shots 返回本次实际 shots。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.prepare_submission

```text
prepare_submission(config: JobSubmissionConfig, *, file_content: bytes | None = None, file_path: str | Path | None = None) -> PreparedSubmission
```

上传输入、校验设备配置并取得报价，返回待确认的实验。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| config | JobSubmissionConfig | 设备、组织、shots 和任务配置。 |
| file_content / file_path | bytes \| None / str \| Path \| None；默认 None | 选择一个输入入口：UTF-8 程序字节，或已有 QASM 文件路径。 |

返回：PreparedSubmission。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.PreparedSubmission

```text
class PreparedSubmission
```

由 prepare_submission 返回，保存本次程序、配置及选中的报价。通过 quote 阅读摘要，再使用 confirm() 接受该报价。

返回：返回对象，由 SchedulerClient.prepare_submission 创建。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| preparation | JobPreparationResultResponse | preparation.id 是本次准备记录与提交查询使用的标识。 |
| quote | QuoteSummary | 公开报价摘要。 |
| currency / total_amount / shots | str / Decimal / int | 本次币种、总金额与 shots。 |
| expires_at_utc | str \| None | 报价有效期。 |

源码：sdk/src/quantum_source_sdk/quotes.py

### quantum_source_sdk.PreparedSubmission.confirm

```text
confirm(*, wait: bool = True) -> Any
```

确认当前报价并请求执行；真机实验按平台报价计费。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| wait | bool = True | True 沿提交等待；False 尽快返回任务对象、排队句柄或提交回执。 |

返回：JobRead、SubmissionReceipt 或 QueuedSubmission，取决于平台当前提交状态。

源码：sdk/src/quantum_source_sdk/quotes.py

### quantum_source_sdk.PreparedSubmission.recover

```text
recover() -> SubmissionReceipt
```

按 preparation.id 重新读取原提交状态，适合恢复一次已发起的确认。

返回：SubmissionReceipt。

源码：sdk/src/quantum_source_sdk/quotes.py

### quantum_source_sdk.SchedulerClient.submit_job

```text
submit_job(config: JobSubmissionConfig, *, file_content: bytes | None = None, file_path: str | Path | None = None) -> JobRead | SubmissionReceipt | QueuedSubmission
```

合并准备、报价审批和执行流程。auto_approve_quote=True 时自动接受报价；人工审价可使用 prepare_submission 与 confirm。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| config | JobSubmissionConfig | 设备、组织、shots 和任务配置。 |
| file_content / file_path | bytes \| None / str \| Path \| None；默认 None | 选择一个输入入口：UTF-8 程序字节，或已有 QASM 文件路径。 |

返回：成功等待后返回 JobRead；提交状态待确认时返回回执或排队句柄。需要审批时 QuoteApprovalRequired.prepared 保留准备对象。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.prepare_submissions

```text
prepare_submissions(configs: Sequence[JobSubmissionConfig], *, file_contents: Sequence[bytes]) -> Any
```

为一组程序分别准备报价并汇总为一个批次。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| configs | Sequence[JobSubmissionConfig] | 按程序顺序排列的任务配置。 |
| file_contents | Sequence[bytes] | 与 configs 一一对应的程序字节。 |

返回：PreparedBatch。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.PreparedBatch

```text
class PreparedBatch
confirm(*, wait: bool = True, timeout: float | None = None) -> tuple[Any, ...]
recover(*, wait: bool = False, timeout: float | None = None) -> tuple[Any, ...]
```

Core 批次对象汇总所有准备任务，confirm 接受已准备的报价，recover 查询已发起的原提交。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| wait / timeout | bool / float \| None | 是否继续等待，以及本次等待秒数。 |

返回：各项任务或回执组成的 tuple。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| quote | QuoteSummary | 设备、任务数、总 shots、金额、币种及有效期。 |
| task_count / total_shots | int / int | 当前准备批次实际包含的任务数和采样总数。 |
| submissions | tuple | 各任务的 Core PreparedSubmission。 |
| job_ids / receipts | tuple | 已经取得的任务 ID 与提交回执。 |
| attempted_preparation_ids / unsubmitted_preparation_ids | tuple[str, ...] | 已尝试提交与尚未提交的准备记录。 |

源码：sdk/src/quantum_source_sdk/batch.py

示例：把自己的 QASM 文件准备成一个可审价的实验。传入已经建立的 scheduler、选中的设备和组织 ID；函数返回 prepared，可读取 prepared.quote。

```python
from quantum_source_sdk import JobSubmissionConfig

def prepare_qasm_file(scheduler, backend_id, organization_id, file_path):
    config = JobSubmissionConfig(
        backend_class_id=backend_id,
        organization_id=organization_id,
        name="my-qasm-experiment",
        shots=128,
        input_format="openqasm2",
    )
    return scheduler.prepare_submission(config, file_path=file_path)
```

## 任务等待与查询

### quantum_source_sdk.SchedulerClient.wait_for_job

```text
wait_for_job(job_id: str, *, timeout: float | None = None, interval: float | None = None, verbose: bool = False, timeout_seconds: float | None = None) -> JobRead
```

轮询已有任务，直到 Completed、Failed 或 Canceled 等终态；读取返回对象的 status 判断结果。超时后可沿同一个 job_id 继续等待。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job_id | str | 真实任务 ID。 |
| timeout | float \| None = None | 本次等待上限；省略时采用客户端 wait_timeout_seconds。 |
| interval | float \| None = None | 本次查询间隔；省略时采用 poll_interval_seconds。 |
| verbose | bool = False | 显示状态变化。 |
| timeout_seconds | float \| None = None | timeout 的兼容别名；同时填写时使用相同值。 |

返回：JobRead；超过等待上限时抛出 TimeoutError。单次设置保持客户端默认值不变。

源码：sdk/src/quantum_source_sdk/clients.py

```text
scheduler.wait_for_job(job_id, timeout=300, interval=2, verbose=True)
```

### quantum_source_sdk.SchedulerClient.wait_for_submission

```text
wait_for_submission(preparation_id: str, *, timeout_seconds: float | None = None, wait_for_completion: bool = True) -> JobRead
```

用准备记录标识跟踪原提交，取得真实任务后继续等待。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| preparation_id | str | prepared.preparation.id 或回执中的原准备 ID。 |
| timeout_seconds | float \| None = None | 本次等待上限。 |
| wait_for_completion | bool = True | True 等待任务完成；False 在取得真实任务对象后返回。 |

返回：JobRead。超时抛出 TimeoutError，可保留原 ID 再次等待；提交失败或取消，以及等待完成时观察到失败或取消任务，会抛出 RuntimeError。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.get_job

```text
get_job(job_id: str) -> JobRead
```

读取已有任务当前状态。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job_id | str | 真实任务 ID。 |

返回：JobRead。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.get_submission

```text
get_submission(preparation_id: str) -> SubmissionReceipt
```

读取一次准备对应的提交状态。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| preparation_id | str | 原准备记录 ID。 |

返回：SubmissionReceipt；job_id 与 job 在平台已建立任务后提供。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.list_jobs

```text
list_jobs(organization_id: str | None = None, limit: int = 20, cursor: str | None = None, status: str | None = None) -> PaginatedJobs
```

按组织和状态分页浏览任务。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| organization_id / status | str \| None = None | 可选组织 ID 与任务状态筛选。 |
| limit | int = 20 | 每页条数。 |
| cursor | str \| None = None | 第一页省略；后续使用上一页 pagination.next_cursor。 |

返回：PaginatedJobs；条目位于 jobs，下一页位置位于 pagination.next_cursor。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.list_submissions

```text
list_submissions(*, limit: int = 50, cursor: str | None = None) -> PaginatedSubmissions
```

分页浏览当前账号的提交记录，包含尚未取得真实任务号的提交。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| limit | int = 50 | 每页记录数。 |
| cursor | str \| None = None | 后续页游标。 |

返回：PaginatedSubmissions；记录位于 submissions。

源码：sdk/src/quantum_source_sdk/clients.py

## 取消与连接释放

### quantum_source_sdk.SchedulerClient.cancel_job

```text
cancel_job(job_id: str) -> None
```

向平台申请取消尚未领取的提交。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job_id | str | 真实任务 ID 或原提交标识。 |

返回：None；平台拒绝取消时抛出对应 APIError。用 get_submission 查询原提交，或用 get_job 查询真实任务。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.cancel_submission

```text
cancel_submission(preparation_id: str) -> SubmissionReceipt
```

用原准备 ID 申请取消尚在提交链路中的任务。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| preparation_id | str | 原准备记录 ID。 |

返回：最新 SubmissionReceipt。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.BaseClient.close

```text
close() -> None
```

释放本地 HTTP 连接。平台任务仍可通过新连接查询；with 语句退出时自动调用。

返回：None。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.download_job_result

```text
download_job_result(job: JobRead) -> UnifiedResult
```

下载并解析统一结果。优先使用任务给出的 output_data_url，也可按任务 ID 访问平台输出接口。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job | JobRead | 带有效 id 的任务对象，通常在任务完成后读取结果。 |

返回：UnifiedResult。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.download_job_output

```text
download_job_output(job: JobRead) -> Any
```

下载任务输出的完整 JSON 响应，保留平台声明的结果通道。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job | JobRead | 带有效 id 的任务对象；可包含 output_data_url。 |

返回：完整响应内容；需要统一结果字段时使用 download_job_result。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.download_job_calibration

```text
download_job_calibration(job: JobRead) -> Any
```

下载任务关联的校准数据。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job | JobRead | 提供 calibration_data_url 的任务对象。 |

返回：校准响应内容。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.UnifiedResult

```text
class UnifiedResult
from_payload(payload: Mapping[str, Any]) -> UnifiedResult
to_dict() -> dict[str, Any]
```

统一结果以 result_kind 标识主要通道，primary_value 返回该通道的数据。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| payload | Mapping[str, Any] | 平台下载的带 result_kind 结果对象。 |

返回：UnifiedResult；字段类型或结果契约不匹配时抛出 ResultContractError。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| result_kind | ResultKind \| str | counts、probabilities、samples、expectation_values 或 raw_provider_result。 |
| counts / probabilities | Mapping \| None | 位串计数或概率。 |
| samples / expectation_values | Sequence \| Mapping \| None | 样本序列或期望值。 |
| primary_value | Any | 当前主要结果。 |
| shots / provider_result | int \| None / Mapping \| None | 采样次数与附带的厂商结果信息。 |

源码：sdk/src/quantum_source_sdk/results.py

### quantum_source_sdk.normalize_result_payload

```text
normalize_result_payload(payload: Mapping[str, Any]) -> UnifiedResult
```

将下载的结果对象规范化为 UnifiedResult。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| payload | Mapping[str, Any] | 包含 result_kind 的结果数据。 |

返回：UnifiedResult。

源码：sdk/src/quantum_source_sdk/results.py

## 报价与配额

### quantum_source_sdk.QuoteSummary

```text
class QuoteSummary
to_dict() -> dict[str, Any]
```

用于审价的公开摘要；金额使用 Decimal，to_dict 将金额输出为字符串。

返回：由准备对象的 quote 属性提供。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| backends | tuple[str, ...] | 目标设备。 |
| task_count / total_shots | int / int | 实际展开的任务数与总 shots。 |
| total_amount / amount | Decimal / str | 总金额及其文本形式。 |
| currency / expires_at_utc | str / str \| None | 币种与有效期。 |

源码：sdk/src/quantum_source_sdk/quotes.py

报价固定本次程序、设备、shots、配置与币种。新任务采用 public + stand；费用由 prepared.quote 给出。组织最多同时占用 10 个非终态任务名额，平台确认 Completed、Failed 或 Canceled 后释放；申请取消后以平台确认状态为准。platform_active_tasks 统计全平台所有用户在该设备上的任务数，范围为已接受且尚未终态的任务，数值为 None 表示尚未提供统计。

## quantum_source_sdk · 设备能力

### 设备记录与解析函数

### quantum_source_sdk.BackendClassRead

```text
class BackendClassRead
```

设备目录和详情的返回模型。通过 get_backend_class 或目录分页取得。

返回：设备记录。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| id / short_code / name | str | 内部标识、用户可选短码、显示名。 |
| status / accepting_jobs | str / bool \| None | 设备状态与是否接收新任务。 |
| num_qubits / supported_formats | int \| None / tuple[str, ...] | 设备宽度与输入格式。 |
| configuration_schema | Mapping[str, Any] | 当前设备选项的类型、默认值及可选范围。 |
| metadata / compilation_mode | Mapping / str | 能力原始数据与编译分工。 |
| platform_active_tasks | int \| None | 全平台在该设备上尚未确认终态的任务数。 |

源码：sdk/src/quantum_source_sdk/models.py

### quantum_source_sdk.capabilities_from_backend

```text
capabilities_from_backend(backend: BackendClassRead) -> BackendCapabilities
```

在本地解析已有设备记录，适合在读取详情后复用。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| backend | BackendClassRead | 设备记录。 |

返回：BackendCapabilities。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.get_capabilities

```text
get_capabilities(short_code: str, *, scheduler: Any | None = None) -> BackendCapabilities
```

从平台读取指定设备并解析能力。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| short_code | str | 当前设备短码。 |
| scheduler | SchedulerClient \| None = None | 复用现有连接；省略时临时创建并关闭客户端。 |

返回：BackendCapabilities。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.fetch_capabilities

```text
fetch_capabilities(short_code: str, scheduler: Any) -> BackendCapabilities
```

使用给定客户端读取设备能力。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| short_code / scheduler | str / SchedulerClient | 设备短码与现有客户端。 |

返回：BackendCapabilities。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.list_backends

```text
list_backends(*, scheduler: Any | None = None) -> list[str]
```

读取所有目录页并列出设备短码。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| scheduler | SchedulerClient \| None = None | 可复用现有连接。 |

返回：list[str]。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.capabilities_from_constraint_data

```text
capabilities_from_constraint_data(short_code: str, constraint_data: Mapping[str, Any], *, fallback_num_qubits: int | None = None, fallback_formats: tuple[str, ...] = ()) -> BackendCapabilities
```

将平台能力字典解析为统一模型，适合目录适配和离线能力检查。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| short_code / constraint_data | str / Mapping[str, Any] | 设备短码与能力数据。 |
| fallback_num_qubits / fallback_formats | int \| None / tuple[str, ...] | 能力字典未提供对应字段时使用的设备记录信息。 |

返回：BackendCapabilities。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.BackendCapabilities

```text
class BackendCapabilities
```

保存设备快照中的门集、拓扑、功能标签和执行路径声明。通常由能力解析函数创建。

返回：只读能力模型。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| supported_ops / supported_gate_names | tuple[GateSpec, ...] / set[str] | 可接收的输入操作及名称。 |
| native_ops / native_gate_names | tuple[GateSpec, ...] / set[str] | 设备公开的原生门及名称。 |
| client_instructions | tuple[GateSpec, ...] | 客户端物理编译可采用的逐门位置声明。 |
| topology / available_qubits | Topology / tuple[int, ...] | 连接图与当前可用物理位置。 |
| compilation_mode / provider_compiles | CompilationMode / bool | 编译分工；provider_compile 表示保持逻辑线路直到厂商入口。 |
| has_client_target | bool | 存在显式 client_instructions，且当前并非 provider_compile。 |
| features / limits | frozenset[str] / dict | 功能标签与任务限制。 |
| timing / noise / snapshot | Mapping | 设备时序、噪声以及快照信息。 |

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.BackendCapabilities.supports_execution_path

```text
supports_execution_path(path: str) -> bool
```

读取平台是否明确声明支持某种输入线路。这是只读能力查询，返回值可用于选择后续准备流程。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| path | str | "logical"：逻辑线路，物理映射留给对应编译流程；"physical"：已经确定物理位置、按物理线路流程提交的程序。 |

返回：只有 raw.execution_paths[path].supported 明确为 True 才返回 True；缺少声明或未声明支持时返回 False。其他 path 值抛出 ValueError。

源码：sdk/src/quantum_source_sdk/backends.py

```python
def describe_execution_paths(caps):
    return {
        "accepts_logical_circuit": caps.supports_execution_path("logical"),
        "accepts_physical_circuit": caps.supports_execution_path("physical"),
    }
```

### quantum_source_sdk.BackendCapabilities.supports_feature

```text
supports_feature(name: str) -> bool
```

按功能名称查询设备标签。allows_custom_gates、allows_reset、allows_mid_circuit_measure、allows_dynamic_circuits、allows_barriers、allows_physical_qubits 和 allows_verbatim_boxes 提供对应的便捷查询。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name | str | 功能名称。 |

返回：bool。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.BackendCapabilities.supports_format

```text
supports_format(name: str) -> bool
```

按语言家族查询设备是否声明支持该类程序；OpenQASM 2 和 3 都归入 qasm 家族。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name | str | 语言家族或格式名称，例如 qasm、openqasm2、openqasm3。 |

返回：bool。具体 OpenQASM 版本结合 supported_formats 的原始声明查看，并由准备接口校验。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.GateSpec

```text
class GateSpec(name: str, arity: int, parameters: tuple[str, ...] = (), qargs: tuple[tuple[int, ...], ...] | None = None)
```

描述一个操作的名称、作用比特数、参数和可用物理位置。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name / arity | str / int | 门名与操作元数。 |
| parameters | tuple[str, ...] = () | 参数名；params 为同一内容的别名。 |
| qargs | tuple[tuple[int, ...], ...] \| None = None | 逐门允许使用的物理位置组合。 |

返回：GateSpec；to_dict() 输出字典。

源码：sdk/src/quantum_source_sdk/backends.py

### quantum_source_sdk.Topology

```text
class Topology(num_qubits: int | None = None, coupling_map: tuple[tuple[int, int], ...] = (), directed: bool = False, available_qubits: tuple[int, ...] | None = None)
```

描述设备连接关系。coupling_map 的每对端点表示一条连接；是否有方向由 is_directed 给出。具体门可用位置同时参考 GateSpec.qargs。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| num_qubits | int \| None = None | 设备位置编号空间的宽度。 |
| coupling_map | tuple[tuple[int, int], ...] = () | 连接边。 |
| directed | bool = False | 连接是否具有方向。 |
| available_qubits | tuple[int, ...] \| None = None | 明确的可用位置集合。 |

返回：Topology；effective_available_qubits 给出解析后的可用位置。

源码：sdk/src/quantum_source_sdk/backends.py

## quantum_source_qiskit · 服务与 Backend

### 服务和设备目录

### quantum_source_qiskit.QuantumSourceService

```text
class QuantumSourceService(*, token: str | None = None, creds: ClientCredentials | None = None, base_url: str | None = None, currency: str | None = None, management_client: ManagementClient | None = None, scheduler_client: SchedulerClient | None = None, **client_options: Any)
```

Qiskit 集成入口，连接平台并创建 Backend、Sampler 与 Estimator。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| currency | str \| None = None | OPEN 或 FULL；省略时沿用注入的 SchedulerClient，或为新客户端采用 OPEN。 |
| token / creds / base_url | 可选 | 平台认证及地址。 |
| management_client / scheduler_client | 客户端 \| None | 成对传入，复用已有目录与任务连接；采用这些客户端已有的认证和连接设置。 |
| **client_options | Any | 新建连接时使用的底层客户端超时等配置。 |

返回：QuantumSourceService；close() 释放服务持有的连接。

源码：sdk/src/quantum_source_qiskit/service.py

### quantum_source_qiskit.QuantumSourceService.organizations

```text
organizations() -> list[dict[str, Any]]
```

读取全部组织页并返回可选组织。

返回：组织字典列表，包含用于后续配置的组织 ID。

源码：sdk/src/quantum_source_qiskit/service.py

### quantum_source_qiskit.QuantumSourceService.backends

```text
backends(*, name: str | None = None, online: bool | None = None, device_type: str | None = None, vendor_id: str | None = None, min_num_qubits: int | None = None, limit: int = 50) -> list[dict[str, Any]]
```

读取并筛选设备目录。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name / online / device_type / vendor_id | str \| bool \| None | 按名称、在线状态、设备类型或厂商筛选。 |
| min_num_qubits | int \| None = None | 所需最小比特数。 |
| limit | int = 50 | 底层每页读取条数。 |

返回：设备字典列表；保留 short_code、platform_active_tasks、configuration_schema 等目录信息。

源码：sdk/src/quantum_source_qiskit/service.py

### quantum_source_qiskit.QuantumSourceService.return_backend

```text
return_backend(name: str, *, config: Mapping[str, Any] | None = None, execution_plan: str | None = None, queue_priority: str | None = None, export_format: str | None = None, capabilities_source: Mapping[str, Any] | str | None = None) -> QuantumSourceBackend
```

获取指定设备的 Qiskit Backend。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name | str | 目录中的设备短码或标识。 |
| config | Mapping \| None = None | 组织 ID、实验名称及设备配置等 Backend 默认值。 |
| execution_plan / queue_priority | str \| None = None | 执行方案与队列等级。 |
| export_format | str \| None = None | 导出格式，如 qasm2、qasm3；省略时按设备能力选择。 |
| capabilities_source | Mapping \| str \| None = None | 用于构建设备能力的显式覆盖数据或文件。 |

返回：QuantumSourceBackend。

源码：sdk/src/quantum_source_qiskit/service.py

### quantum_source_qiskit.QuantumSourceService.return_target

```text
return_target(name: str, *, capabilities_source: Mapping[str, Any] | str | None = None) -> Target
```

读取设备并构建 Qiskit Target。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name / capabilities_source | str / Mapping \| str \| None | 设备标识和可选能力覆盖。 |

返回：qiskit.transpiler.Target。

源码：sdk/src/quantum_source_qiskit/service.py

### Backend 配置、编译与执行

### quantum_source_qiskit.QuantumSourceBackend

```text
class QuantumSourceBackend
```

由 service.return_backend 返回的 BackendV2 对象，衔接线路校验、编译、报价和平台任务。

返回：Qiskit BackendV2 兼容对象。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| capabilities | BackendCapabilities | 完整平台能力。 |
| configuration_schema / options | dict / Qiskit Options | 设备声明的选项与当前有效默认值。 |
| target / coupling_map | Target / CouplingMap \| None | 客户端编译使用的门指令与连接关系。 |
| available_qubits / max_shots / max_circuits | tuple / int \| None / int \| None | 可用位置及任务限制。 |
| provider_compiles / compilation_mode | bool / CompilationMode | 编译分工。 |

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.QuantumSourceBackend.set_options

```text
set_options(**fields: Any) -> None
```

更新该 Backend 后续调用的默认选项。动态设备字段来自 configuration_schema；将某个设备覆盖项设为 None 可恢复对应路径的默认选择。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| **fields | Any | 如 shots，以及设备声明的 mapping、optimization、amend。 |

返回：None。

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.QuantumSourceBackend.transpile

```text
transpile(circuits: Any, *, physical_qubits: Any = None, **transpile_kwargs: Any) -> Any
```

在本地生成适合目标设备的线路。physical_qubits 或 initial_layout 按逻辑线顺序指定物理位置。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuits | QuantumCircuit 或线路序列 | 待编译线路。 |
| physical_qubits | Any = None | 指定物理编号序列。 |
| **transpile_kwargs | Any | Qiskit 编译参数，例如 initial_layout、optimization_level。 |

返回：编译后的 QuantumCircuit 或线路列表。固定布局使用显式物理 Target 与直接连接。

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.QuantumSourceBackend.validate_circuit

```text
validate_circuit(circuit: Any, *, shots: int | None = None, physical_qubits: Any = None, initial_layout: Any = None, _execution_path: str | None = None) -> None
```

检查线路宽度、shots、所需功能以及布局是否满足当前设备能力。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuit | QuantumCircuit | 待检查线路。 |
| shots / physical_qubits / initial_layout | 可选 | 本次采样次数与布局。 |
| _execution_path | str \| None = None | SDK 内部路径入口，常规调用保持默认。 |

返回：校验通过返回 None；不满足能力时抛出对应异常。

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.QuantumSourceBackend.prepare

```text
prepare(circuits: Any, /, *, job_subcategory_id: str | None = None, backend_class_id: str | None = None, organization_id: str | None = None, name: str | None = None, configuration_data: Mapping[str, Any] | None = None, execution_plan: str | None = None, queue_priority: str | None = None, physical_qubits: Any = None, initial_layout: Any = None, **run_options: Any) -> PreparedQuantumSourceJob
```

为一条或多条 QuantumCircuit 准备完整报价。单次显式配置优先于 Backend 默认值。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuits | QuantumCircuit 或线路序列；位置参数 | 本次待执行的线路。 |
| organization_id / name / job_subcategory_id | str \| None = None | 本次组织、名称与分类。 |
| backend_class_id | str \| None = None | 平台设备标识，默认使用当前 Backend。 |
| configuration_data | Mapping \| None = None | 本次设备选项的扁平字典。 |
| physical_qubits / initial_layout | Any = None | 两个等价布局入口，选择其中一个。 |
| execution_plan / queue_priority | str \| None = None | 继承 Backend 配置。 |
| **run_options | Any | shots、verbose、job_timeout_seconds 及 schema 声明的动态设备选项。 |

返回：PreparedQuantumSourceJob，包含全部实际任务的 quote。

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.QuantumSourceBackend.run

```text
run(circuits: Any, /, *, auto_approve_quote: bool | None = None, **run_options: Any) -> QuantumSourceJob | QueuedQuantumSourceJob
```

直接准备并执行线路。默认自动接受报价；需要逐次审价时使用 prepare 与 confirm。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuits | QuantumCircuit 或线路序列 | 本次线路。 |
| auto_approve_quote | bool \| None = None | 继承配置，默认自动接受报价。 |
| **run_options | Any | prepare 支持的单次选项。 |

返回：QuantumSourceJob 或 QueuedQuantumSourceJob；需要审批时通过 QuoteApprovalRequired.prepared 取得准备对象。

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.PreparedQuantumSourceJob

```text
class PreparedQuantumSourceJob
confirm(*, accepted_quotes: Iterable[tuple[str | None, str | None]] | None = None) -> QuantumSourceJob | QueuedQuantumSourceJob | PreparedSubmissionReceipt
recover() -> QuantumSourceJob | QueuedQuantumSourceJob | PreparedSubmissionReceipt
```

保存多线路实验的完整报价。confirm 默认接受当前绑定报价；recover 沿原提交查询。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| accepted_quotes | Iterable[tuple[str \| None, str \| None]] \| None = None | 显式报价确认标识；常规使用保留默认，直接调用 confirm()。 |

返回：任务对象或仍在核实中的 PreparedSubmissionReceipt。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| quote | QuoteSummary | 设备、任务数、总 shots、金额、币种及有效期。 |
| task_count / total_shots | int / int | 当前准备批次实际包含的任务数和采样总数。 |
| submissions | tuple | 各任务的 Core PreparedSubmission。 |
| platform_job_ids | tuple[str, ...] | 已取得的真实平台任务 ID。 |

源码：sdk/src/quantum_source_qiskit/backend.py

### quantum_source_qiskit.QuantumSourceJob

```text
class QuantumSourceJob
result(timeout: float | None = None, wait: float = 2.0) -> Result
status() -> JobStatus
cancel() -> bool
```

查询已提交实验并取得 Qiskit 原生 Result。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| timeout | float \| None = None | 本次结果等待上限。 |
| wait | float = 2.0 | 状态查询间隔秒数。 |

返回：result 返回 qiskit.result.Result，可调用 get_counts()；status 返回 JobStatus，cancel 返回取消请求结果。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| platform_job_ids | tuple[str, ...] | 批次中的真实任务 ID。 |
| job_id() | str | Qiskit 任务标识。 |

源码：sdk/src/quantum_source_qiskit/job.py

### quantum_source_qiskit.build_target

```text
build_target(capabilities: BackendCapabilities) -> Target
```

将平台能力转换为 Qiskit Target，按逐门 qargs 建立物理指令，并采用实际提供的 duration / error 数据。provider_compile 路径保留其逻辑输入语义。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| capabilities | BackendCapabilities | 设备能力快照。 |

返回：Target。

源码：sdk/src/quantum_source_qiskit/target.py

### quantum_source_qiskit.export_circuit_to_qasm

```text
export_circuit_to_qasm(circuit: Any, fmt: str, *, backend: Any | None = None) -> bytes
```

将已有 Qiskit 线路导出为程序字节，供文件或 Core 接口复用。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuit / fmt | QuantumCircuit / str | 线路与 qasm2 或 qasm3 格式。 |
| backend | Any \| None = None | 可选目标设备，用于能力适配。 |

返回：UTF-8 编码的 bytes。

源码：sdk/src/quantum_source_qiskit/qasm.py

### quantum_source_qiskit.circuit_to_qasm

```text
circuit_to_qasm(circuit: Any, export_format: str = "qasm3") -> str
```

将 QuantumCircuit 导出为 OpenQASM 字符串。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuit | QuantumCircuit | 输入线路。 |
| export_format | str = "qasm3" | 导出版本。 |

返回：str。

源码：sdk/src/quantum_source_qiskit/qasm.py

## quantum_source_qiskit · Sampler 与 Estimator

### quantum_source_qiskit.QuantumSourceService.create_sampler

```text
create_sampler(*, backend: Any, organization_id: str | None = None, job_subcategory_id: str = "oth:oth", name: str | None = None, configuration_data: Mapping[str, Any] | None = None, execution_plan: str | None = None, queue_priority: str | None = None, export_format: str | None = None, auto_approve_quote: bool | None = None, options: Mapping[str, Any] | None = None) -> QuantumSourceSampler
```

复用当前服务连接创建 Sampler。SamplerV2 是 QuantumSourceSampler 的导出别名。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| backend | Backend 或设备标识 | 要采样的设备。 |
| options | Mapping \| None = None | Sampler 默认设置，例如 default_shots。 |
| 其余关键字 | 见签名 | 任务、设备配置及报价审批默认值，与 Backend 流程一致。 |

返回：QuantumSourceSampler。

源码：sdk/src/quantum_source_qiskit/service.py

### quantum_source_qiskit.QuantumSourceService.create_estimator

```text
create_estimator(*, backend: Any, organization_id: str | None = None, job_subcategory_id: str = "oth:oth", name: str | None = None, configuration_data: Mapping[str, Any] | None = None, execution_plan: str | None = None, queue_priority: str | None = None, export_format: str | None = None, auto_approve_quote: bool | None = None, options: Mapping[str, Any] | None = None) -> QuantumSourceEstimator
```

复用当前服务连接创建 Estimator。EstimatorV2 是 QuantumSourceEstimator 的导出别名。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| backend | Backend 或设备标识 | 执行测量的设备。 |
| options | Mapping \| None = None | Estimator 默认设置，例如 default_precision。 |
| 其余关键字 | 见签名 | 任务、设备配置及报价审批默认值。 |

返回：QuantumSourceEstimator。

源码：sdk/src/quantum_source_qiskit/service.py

### quantum_source_qiskit.QuantumSourceSampler.prepare

```text
prepare(pubs: Iterable[Any], *, shots: int | None = None, export_format: str | None = None, physical_qubits: Any = None, initial_layout: Any = None, execution_plan: str | None = None, queue_priority: str | None = None, configuration_data: Mapping[str, Any] | None = None, **run_options: Any) -> PreparedQuantumSourcePrimitive
```

展开 PUB 参数绑定，为每条实际采样线路准备报价。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| shots | int \| None = None | 本次默认 shots；PUB 内显式 shots 优先。 |
| export_format | str \| None = None | 本次 OpenQASM 导出版本。 |
| pubs | Iterable[Any] | Sampler PUB 为线路或 (线路, 参数值[, shots])；Estimator PUB 为 (线路, 可观测量[, 参数值[, precision]])。 |
| physical_qubits / initial_layout | Any = None | 选择一个布局入口，将逻辑线分配至指定物理位置。 |
| configuration_data | Mapping[str, Any] \| None = None | 单次设备选项，使用设备 configuration_schema 中的字段。 |
| execution_plan / queue_priority | str \| None = None | 继承构造配置；当前新任务采用 public / stand。 |
| **run_options | Any | 传给 Backend 的其他运行选项。 |

返回：PreparedQuantumSourcePrimitive。确认后的结果为 PrimitiveResult，按经典寄存器提供 BitArray。

源码：sdk/src/quantum_source_qiskit/sampler.py

### quantum_source_qiskit.QuantumSourceSampler.run

```text
run(pubs: Iterable[Any], *, shots: int | None = None, export_format: str | None = None, auto_approve_quote: bool | None = None, physical_qubits: Any = None, initial_layout: Any = None, execution_plan: str | None = None, queue_priority: str | None = None, configuration_data: Mapping[str, Any] | None = None, **run_options: Any) -> Any
```

直接准备并执行采样 PUB；结果对象遵循 Qiskit SamplerV2 结构。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| pubs / shots | Iterable / int \| None | 与 prepare 相同。 |
| auto_approve_quote | bool \| None = None | 本次报价审批策略。 |
| 其余关键字 | 见 prepare | 单次编译与设备选项。 |

返回：正常返回 QuantumSourcePrimitiveJob，调用 result() 读取结果。待确认时抛出 BatchSubmissionPendingError，使用异常的 prepared 与 receipt 恢复；需要审批时抛出 QuoteApprovalRequired。

源码：sdk/src/quantum_source_qiskit/sampler.py

### quantum_source_qiskit.QuantumSourceEstimator.prepare

```text
prepare(pubs: Iterable[Any], *, precision: float | None = None, physical_qubits: Any = None, initial_layout: Any = None, execution_plan: str | None = None, queue_priority: str | None = None, configuration_data: Mapping[str, Any] | None = None, **run_options: Any) -> PreparedQuantumSourcePrimitive
```

将可观测量展开为实际测量任务并准备完整报价。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| precision | float \| None = None | 目标统计精度；PUB 内显式精度优先，用于确定采样预算。 |
| pubs | Iterable[Any] | Sampler PUB 为线路或 (线路, 参数值[, shots])；Estimator PUB 为 (线路, 可观测量[, 参数值[, precision]])。 |
| physical_qubits / initial_layout | Any = None | 选择一个布局入口，将逻辑线分配至指定物理位置。 |
| configuration_data | Mapping[str, Any] \| None = None | 单次设备选项，使用设备 configuration_schema 中的字段。 |
| execution_plan / queue_priority | str \| None = None | 继承构造配置；当前新任务采用 public / stand。 |
| **run_options | Any | 传给 Backend 的其他运行选项。 |

返回：PreparedQuantumSourcePrimitive；确认后的结果 data.evs 为期望值，data.stds 为统计估计。

源码：sdk/src/quantum_source_qiskit/estimator.py

### quantum_source_qiskit.QuantumSourceEstimator.run

```text
run(pubs: Iterable[Any], *, precision: float | None = None, auto_approve_quote: bool | None = None, physical_qubits: Any = None, initial_layout: Any = None, execution_plan: str | None = None, queue_priority: str | None = None, configuration_data: Mapping[str, Any] | None = None, **run_options: Any) -> Any
```

直接准备并执行期望值任务。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| pubs / precision | Iterable / float \| None | 与 prepare 相同。 |
| auto_approve_quote | bool \| None = None | 本次报价审批策略。 |
| 其余关键字 | 见 prepare | 单次编译与设备选项。 |

返回：正常返回 QuantumSourcePrimitiveJob，调用 result() 读取结果。待确认时抛出 BatchSubmissionPendingError，使用异常的 prepared 与 receipt 恢复；需要审批时抛出 QuoteApprovalRequired。

源码：sdk/src/quantum_source_qiskit/estimator.py

### quantum_source_qiskit.PreparedQuantumSourcePrimitive

```text
class PreparedQuantumSourcePrimitive
confirm(*, accepted_quotes: Any = None) -> Any
recover() -> Any
```

保存一次 Sampler / Estimator 调用展开后的完整报价和结果还原规则。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| accepted_quotes | Any = None | 默认确认已绑定报价。 |

返回：QuantumSourcePrimitiveJob 或 PreparedSubmissionReceipt。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| quote | QuoteSummary | 设备、任务数、总 shots、金额、币种及有效期。 |
| task_count / total_shots | int / int | 当前准备批次实际包含的任务数和采样总数。 |
| submissions | tuple | 各任务的 Core PreparedSubmission。 |

源码：sdk/src/quantum_source_qiskit/prepared_primitive.py

### quantum_source_qiskit.QuantumSourcePrimitiveJob

```text
class QuantumSourcePrimitiveJob
result(timeout: float | None = None) -> Any
status() -> Any
cancel() -> bool
```

等待底层平台任务并还原 PrimitiveResult。timeout 约束本地等待；稍后可继续读取同一对象。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| timeout | float \| None = None | 本次等待上限秒数。 |

返回：result 返回对应 Sampler / Estimator 的 PrimitiveResult。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| platform_job_ids / submission_ids | tuple[str, ...] | 平台任务及提交标识。 |
| metadata | dict | 实际任务和结果元数据。 |

源码：sdk/src/quantum_source_qiskit/prepared_primitive.py

示例：为已有 QuantumCircuit 创建 Sampler 报价。函数返回的 prepared.quote 汇总实际任务；接受报价后调用 prepared.confirm()，再从任务的 result() 读取采样结果。

```python
def prepare_sampling(service, backend, circuit, shots=128):
    sampler = service.create_sampler(backend=backend)
    return sampler.prepare([circuit], shots=shots)
```

## quantum_source_pennylane · Device

### quantum_source_pennylane.QuantumSourceDevice

```text
class QuantumSourceDevice(wires: Any, shots: Any = None, backend: str = "", *, auto_confirm: bool = True, scheduler: Any | None = None, currency: str | None = None, token: str | None = None, client_id: str | None = None, client_secret: str | None = None, base_url: str | None = None, api_url: str | None = None, organization_id: str | None = None, provider: str | None = None, configuration_data: Mapping[str, Any] | None = None, job_subcategory_id: str = "oth:oth", execution_plan: str = "public", queue_priority: str = "stand", auto_approve_quote: bool | None = None, verbose: bool = False, provider_probability_shots: int | None = None, job_timeout_seconds: float = 86400.0, job_name_prefix: str = "pennylane-job")
```

PennyLane Device，亦可用 qml.device("quantum_source.device", ...) 创建。线路使用逻辑 wires，由插件生成 OpenQASM 并提交平台。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| wires / backend | Any / str | 逻辑 wires 和当前设备 short_code。 |
| shots | Any = None | 有限 shots 采样，或 shots=None 的概率路径；具体测量支持见设备声明。 |
| auto_confirm / auto_approve_quote | bool = True / bool \| None = None | 自动确认开关及其兼容配置入口。 |
| scheduler / currency | SchedulerClient \| None / str \| None | 复用连接或选择 OPEN / FULL 钱包。 |
| token / client_id / client_secret | str \| None | 平台认证信息；也支持环境凭据。 |
| base_url / api_url | str \| None | 平台地址及兼容命名入口。 |
| organization_id / provider | str \| None | 组织 ID 与可选厂商。 |
| configuration_data | Mapping \| None = None | 按设备 schema 配置云端选项。 |
| execution_plan / queue_priority | str = "public" / "stand" | 执行方案与队列等级。 |
| job_subcategory_id / job_name_prefix | str = "oth:oth" / "pennylane-job" | 任务分类和名称前缀。 |
| verbose / job_timeout_seconds | bool = False / float = 86400.0 | 等待状态输出与等待上限。 |
| provider_probability_shots | int \| None = None | 概率路径在厂商侧使用的 shots 预算。 |

返回：QuantumSourceDevice。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| provider_capabilities | BackendCapabilities | 平台设备能力；PennyLane capabilities 描述框架操作和测量支持。 |
| features | list[str] | 平台功能标签。 |
| job_ids / jobs / submission_receipts | tuple | 已经观察到的任务 ID、任务对象和提交回执。 |
| last_execution_metadata | dict | 本次展开任务数、每任务 shots 和采样语义。 |

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.QuantumSourceDevice.prepare

```text
prepare(circuits: QuantumScript | Sequence[QuantumScript], execution_config: ExecutionConfig | None = None) -> PreparedPennyLaneBatch
```

冻结当前 QuantumScript 或脚本序列，经预处理后为所有实际任务准备报价。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuits | QuantumScript 或脚本序列 | 可通过 qnode.construct(args, kwargs) 取得具体参数下的 tape。 |
| execution_config | ExecutionConfig \| None = None | PennyLane 执行配置。 |

返回：PreparedPennyLaneBatch，保留原测量结构和还原方法。

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.QuantumSourceDevice.execute

```text
execute(circuits: QuantumScript | Sequence[QuantumScript], execution_config: ExecutionConfig | None = None) -> Any
```

准备并执行当前批次，通常由 QNode 的执行系统调用。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| circuits / execution_config | 同 prepare | 当前批次与 PennyLane 执行配置。 |

返回：与输入脚本及测量结构相对应的结果；需要审批时 QuoteApprovalRequired.prepared 保存当前批次。

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.QuantumSourceDevice.preprocess_transforms

```text
preprocess_transforms(execution_config: ExecutionConfig | None = None) -> Any
```

构建 PennyLane 预处理流程，完成能力校验、观测量处理、测量分组和操作分解。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| execution_config | ExecutionConfig \| None = None | 本次执行配置。 |

返回：PennyLane transform program；执行后给出实际脚本和结果还原函数。

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.PreparedPennyLaneBatch

```text
class PreparedPennyLaneBatch
confirm(*, wait: bool = True, timeout: float | None = None) -> Any
recover(*, wait: bool = False, timeout: float | None = None) -> Any
result(timeout: float | None = None) -> Any
```

保存一个具体脚本批次的报价、逻辑程序和测量还原规则。confirm 请求执行，recover 查询原提交，result 等待并还原测量结果。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| wait / timeout | bool / float \| None | 是否等待结果及本次等待秒数。 |

返回：wait=True 时返回原脚本测量结构；wait=False 保留可继续查询的批次对象。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| quote | QuoteSummary | 设备、任务数、总 shots、金额、币种及有效期。 |
| task_count / total_shots | int / int | 当前准备批次实际包含的任务数和采样总数。 |
| submissions | tuple | 各任务的 Core PreparedSubmission。 |
| programs | tuple[str, ...] | 用于准备报价的 OpenQASM 程序。 |
| job_ids / receipts / created_jobs | tuple | 已取得的任务 ID、回执及任务对象。 |

源码：sdk/src/quantum_source_pennylane/prepared.py

### quantum_source_pennylane.QuantumSourceDevice.supports_feature

```text
supports_feature(name: str) -> bool
```

查询平台功能标签。实际 QNode 支持范围同时由 PennyLane 静态能力声明及预处理流程决定。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| name | str | 功能名称。 |

返回：bool。allows_custom_gates、allows_reset、allows_mid_circuit_measure、allows_dynamic_circuits、allows_barriers 提供便捷查询。

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.QuantumSourceDevice.refresh_job

```text
refresh_job(job_id: str | None = None) -> Any
```

刷新已提交任务的状态。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job_id | str \| None = None | 指定任务 ID；省略时使用最近记录的任务。 |

返回：最新任务对象。

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.QuantumSourceDevice.cancel_job

```text
cancel_job(job_id: str | None = None) -> None
```

向平台申请取消尚未领取的提交。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job_id | str \| None = None | 提交号或真实任务号；省略时优先使用 last_prepared 中最近已尝试的提交号，其次使用最近任务号。 |

返回：None。持有提交号时通过 scheduler.get_submission 查询；持有真实任务号时通过 refresh_job 查询。

源码：sdk/src/quantum_source_pennylane/device.py

### quantum_source_pennylane.QuantumSourceDevice.close

```text
close() -> None
```

释放设备持有的客户端连接。

返回：None。

源码：sdk/src/quantum_source_pennylane/device.py

示例：将一个 QNode 在具体参数下的线路交给 prepare，报价和返回结果都对应这一次参数取值。

```python
def prepare_qnode(qnode, *args, **kwargs):
    tape = qnode.construct(args, kwargs)
    return qnode.device.prepare(tape)
```

## quantum_source_sdk · 底层协议与返回模型

底层接口适用于需要分别管理上传、准备、报价确认和任务创建的应用。高层 prepare_submission 已封装这些步骤。

### quantum_source_sdk.SchedulerClient.upload_job_input

```text
upload_job_input(*, file_content: bytes | None = None, file_path: str | Path | None = None, execution_plan: str = "public") -> str
```

上传程序并取得后续准备请求使用的上传标识。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| file_content / file_path | bytes \| str \| Path \| None | 选择字节或文件路径入口。 |
| execution_plan | str = "public" | 上传对应的执行方案。 |

返回：upload_endpoint_id 字符串。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.JobPreparationCreate

```text
class JobPreparationCreate(organization_id: str | None, backend_class_id: str, name: str, upload_endpoint_id: str, job_subcategory_id: str, shots: int, configuration_data: Mapping[str, Any] | None = None, input_format: str = "qasm", submitted_with: str = "sdk", project_id: str | None = None, currency: str = "OPEN", execution_plan: str = "public", queue_priority: str = "stand")
```

底层准备请求，关联已经上传的程序和任务配置。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| organization_id / backend_class_id / name | str \| None / str / str | 组织、设备与实验名称。 |
| upload_endpoint_id | str | upload_job_input 的返回值。 |
| job_subcategory_id / shots | str / int | 任务分类与采样次数。 |
| configuration_data / input_format | Mapping \| None / str | 设备配置与程序格式。 |
| currency / execution_plan / queue_priority | str = "OPEN" / "public" / "stand" | 本次报价使用的钱包、执行方案和队列等级。 |
| submitted_with / project_id | str = "sdk" / str \| None = None | 提交来源和可选项目。 |

返回：JobPreparationCreate。

源码：sdk/src/quantum_source_sdk/models.py

### quantum_source_sdk.SchedulerClient.prepare_job

```text
prepare_job(preparation: JobPreparationCreate) -> JobPreparationResponse
```

发起底层准备请求。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| preparation | JobPreparationCreate | 完整准备数据。 |

返回：JobPreparationResponse；id 用于读取准备结果。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.SchedulerClient.get_preparation_result

```text
get_preparation_result(preparation_id: str) -> JobPreparationResultResponse
```

读取准备进度和平台给出的报价方案。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| preparation_id | str | 准备记录 ID。 |

返回：JobPreparationResultResponse；status 表示进度，quote 保存可用方案。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.JobCreate

```text
class JobCreate(job_preparation_id: str, execution_plan_id: str, queue_priority_id: str, organization_id: str | None = None, accepted_quote_id: str | None = None, accepted_quote_hash: str | None = None, confirm_hardware: bool = False)
```

底层任务创建请求，将准备结果中的方案、队列及已接受报价关联到一次执行。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job_preparation_id / execution_plan_id / queue_priority_id | str | 准备 ID、选中的报价方案 ID 和队列 ID。 |
| organization_id | str \| None = None | 组织 ID。 |
| accepted_quote_id / accepted_quote_hash | str \| None = None | 与本次接受报价一致的标识及摘要。 |
| confirm_hardware | bool = False | 明确确认真机执行时设为 True。 |

返回：JobCreate。

源码：sdk/src/quantum_source_sdk/models.py

### quantum_source_sdk.SchedulerClient.create_job

```text
create_job(job: JobCreate) -> JobRead | SubmissionReceipt
```

向平台提交已确认的底层请求。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| job | JobCreate | 完整创建请求。 |

返回：已建立的 JobRead，或仍在提交中的 SubmissionReceipt。

源码：sdk/src/quantum_source_sdk/clients.py

### quantum_source_sdk.JobRead

```text
class JobRead
```

真实平台任务的查询结果。

返回：由任务创建、查询和等待方法返回。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| id / status / provider_status | str / str / str \| None | 任务 ID、平台状态和厂商状态。 |
| backend_class_id / backend_name / shots | str / str / int | 目标设备与采样次数。 |
| job_preparation_id | str \| None | 关联准备记录。 |
| output_data_url / calibration_data_url | str \| None | 结果和校准数据地址。 |
| message / submitted_at / completed_at | str \| None | 状态说明与时间记录。 |

源码：sdk/src/quantum_source_sdk/models.py

### quantum_source_sdk.SubmissionReceipt

```text
class SubmissionReceipt
```

尚在提交或核实阶段的回执，可用原准备 ID 持续查询。

返回：由提交与恢复方法返回。

| 属性 | 类型 / 内容 | 用途 |
| --- | --- | --- |
| submission_id / job_preparation_id | str | 提交标识和准备记录标识。 |
| submission_status / preparation_status / billing_status | str / str \| None / str \| None | 提交、准备和计费进度。 |
| job_id / job | str \| None / JobRead \| None | 取得真实任务后提供。 |
| message / reused | str \| None / bool | 状态说明及是否复用了已有提交。 |

源码：sdk/src/quantum_source_sdk/models.py

### quantum_source_sdk.QueuedSubmission

```text
class QueuedSubmission
refresh() -> SubmissionReceipt
wait(timeout: float | None = None) -> JobRead
result(timeout: float | None = None) -> Any
cancel() -> Any
```

高层排队句柄，保留提交身份并衔接后续真实任务。

| 参数 | 类型 / 默认值 | 说明 |
| --- | --- | --- |
| timeout | float \| None = None | 本次等待上限。 |

返回：refresh 返回回执；wait 返回真实任务；result 下载结果。

源码：sdk/src/quantum_source_sdk/submission.py

## 异常与恢复

| 异常 | 可读取内容 | 后续操作 |
| --- | --- | --- |
| QuoteApprovalRequired | prepared | 查看 prepared.quote，接受后调用 confirm()。 |
| SubmissionPendingError | receipt | 使用 receipt 的原准备 ID 查询提交。 |
| BatchSubmissionPendingError | prepared / receipt（按所属包） | 保留批次并通过 recover() 查询原提交。 |
| APIError 及子类 | 平台错误类型、简短说明；部分流程附带 prepared | 根据平台返回的条件修正配置或查询原任务。 |
| JobLimitReachedError | 组织名额相关错误 | 等待现有任务终态后，按业务需要发起新任务。 |
| ResultContractError | 结果类型或字段校验说明 | 核对 result_kind 和返回数据通道。 |
| TimeoutError | 本次等待已超过上限 | 保留任务 ID 或批次对象，继续查询同一实验。 |

异常模型见 sdk/src/quantum_source_sdk/models.py、quotes.py、batch.py 与 results.py；Qiskit 批次异常还定义在 quantum_source_qiskit/backend.py。

## 常用调用与教程入口

本参考集中描述调用契约。要完成一次实验，可从教程选择设备、构造输入、准备报价，再确认执行和读取结果。

- [Core：使用自己的 QASM 文件](core.html#framework-input)
- [Core：设备配置](capabilities-core.html)
- [Qiskit：Options 与 Target](capabilities-qiskit.html)
- [Qiskit：编译与物理布局](compilation.html)
- [Sampler 与 Estimator](qiskit-primitives.html)
- [PennyLane：测量、shots 与梯度](pennylane-measurements.html)
- [底层提交协议](low-level.html)

## 实现与验证索引

下表集中收录各教程原有的接口依据。源码路径相对项目根目录；条目上方的源码位置可用于查阅准确实现。公开接口与内部实现辅助函数分开列示，测试用于验证行为。

| 主题 | 实现位置 | 验证位置 |
| --- | --- | --- |
| 连接、分页、查询、等待及结果下载 | sdk/src/quantum_source_sdk/clients.py；models.py；auth.py；results.py | backend/frontend/tests/test_guide_examples.py |
| 高层准备、报价冻结、单任务与批次确认 | sdk/src/quantum_source_sdk/clients.py：prepare_submission、prepare_submissions；quotes.py；batch.py；submission.py | sdk/tests/test_sdk_queued_submissions.py；backend/frontend/tests/test_guide_examples.py |
| 底层上传与任务创建协议 | sdk/src/quantum_source_sdk/clients.py：upload_job_input、prepare_job、get_preparation_result、create_job；models.py；utils.py | backend/frontend/tests/test_guide_examples.py |
| 设备能力解析、兼容字段、QASM 格式、时序与噪声 | sdk/src/quantum_source_sdk/backends.py：BackendCapabilities、capabilities_from_backend、capabilities_from_constraint_data、get_capabilities、list_backends | sdk/tests/test_openquantum_package_contract.py |
| 设备配置 schema、扁平配置与执行路径 | sdk/src/quantum_source_sdk/execution_options.py；clients.py：_submission_compiler_configuration；backend/src/quantum_source/compiler_configuration.py | sdk/tests/test_device_configuration_options.py；sdk/tests/test_framework_compiler_controls.py |
| 平台能力发布与程序校验 | backend/src/quantum_source/sdk_gateway/service.py：_backend_payload、_validate_program；本源适配器运行时的 ChipInfo 与执行选项处理 | sdk/tests/test_selected_device_options.py |
| Qiskit 目录、详情与服务工厂 | sdk/src/quantum_source_qiskit/service.py：backends、return_backend、return_target、_backend_dict、create_sampler、create_estimator；service_accounts.py | sdk/tests/test_qiskit_dynamic_device_options.py |
| Options 初始化与单次覆盖 | sdk/src/quantum_source_qiskit/backend.py：_device_option_defaults、configuration_schema、set_options、prepare | sdk/tests/test_qiskit_dynamic_device_options.py；sdk/tests/test_selected_device_options.py |
| Target、门位置、物理布局与导出 | sdk/src/quantum_source_qiskit/target.py：build_target；backend.py：transpile；qasm.py：resolve_export_format、export_circuit_to_qasm | sdk/tests/test_qiskit_dynamic_capability_target.py；backend/frontend/tests/test_guide_qiskit_examples.py |
| Sampler PUB、shots 与 BitArray | sdk/src/quantum_source_qiskit/sampler.py：_coerce_pubs、_prepare、_run | sdk/tests/test_qiskit_primitives_alignment.py；backend/frontend/tests/test_guide_qiskit_examples.py |
| Estimator precision、测量分组和 evs / stds | sdk/src/quantum_source_qiskit/estimator.py：prepare、_reduce | sdk/tests/test_qiskit_primitives_alignment.py |
| Primitive 等待、状态与恢复 | sdk/src/quantum_source_qiskit/prepared_primitive.py：QuantumSourcePrimitiveJob、PreparedQuantumSourcePrimitive | sdk/tests/test_sdk_queued_submissions.py；backend/frontend/tests/test_guide_qiskit_examples.py |
| PennyLane 构造、平台能力与逻辑 wires | sdk/src/quantum_source_pennylane/device.py：__init__、features、supports_feature、provider_capabilities、_get_backend、_prepare_measurement_tape | sdk/tests/test_pennylane_capability_qasm.py；sdk/tests/test_framework_compiler_controls.py |
| PennyLane 框架操作、设备选项与 QASM | sdk/src/quantum_source_pennylane/device_config.toml；device.py：_validate_execution_controls、_build_submission_config；qasm_serializer.py | sdk/tests/test_pennylane_capability_qasm.py；backend/frontend/tests/test_guide_pennylane_examples.py |
| PennyLane 测量分解、shots、广播与梯度 | sdk/src/quantum_source_pennylane/device.py：preprocess_transforms、prepare、execute、_validate_analytic_contract | sdk/tests/test_pennylane_release_feature_acceptance.py |
| PennyLane 报价、程序快照与结果还原 | sdk/src/quantum_source_pennylane/prepared.py：quote、task_count、total_shots、programs、confirm、recover、_collect_results | sdk/tests/test_pennylane_release_feature_acceptance.py；backend/frontend/tests/test_guide_pennylane_examples.py |

## 下载本页 Jupyter Notebook

收录本页 Python 示例与说明，便于在 Jupyter Notebook 中学习和运行；安装命令保留为说明。

[下载《API 参考》Notebook（.ipynb）](../../notebooks/sdk_user_guide_api.ipynb)