API 参考

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

• Core 与认证
• 设备能力
• Qiskit
• PennyLane
• 底层协议
• 实现与验证索引

quantum_source_sdk · 连接与任务

quantum_source_sdk.ClientCredentials

class ClientCredentials(client_id: str, client_secret: str)

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

返回：ClientCredentials。

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

quantum_source_sdk.credentials_from_environment

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

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

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

返回：ClientCredentials。

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

quantum_source_sdk.BaseClient

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 上下文。

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

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

客户端级钱包选择

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

quantum_source_sdk.SchedulerClient

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；新准备请求采用当前客户端的钱包。

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

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

quantum_source_sdk.ManagementClient

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

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

返回：ManagementClient。

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

quantum_source_sdk.ManagementClient.list_user_organizations

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

读取当前账号可用组织。

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

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

quantum_source_sdk.ManagementClient.list_providers

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

读取厂商目录。

返回：PaginatedProviders；条目位于 providers。

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

quantum_source_sdk.ManagementClient.list_backend_classes

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

读取分页设备目录。

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

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

quantum_source_sdk.ManagementClient.get_credit_balance

get_credit_balance(organization_id: str) -> CreditBalanceRead

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

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

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

quantum_source_sdk.SchedulerClient.get_backend_class

get_backend_class(identifier: str) -> BackendClassRead

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

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

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

任务配置与准备

quantum_source_sdk.JobSubmissionConfig

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。

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

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

quantum_source_sdk.SchedulerClient.prepare_submission

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

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

返回：PreparedSubmission。

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

quantum_source_sdk.PreparedSubmission

class PreparedSubmission

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

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

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

quantum_source_sdk.PreparedSubmission.confirm

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

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

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

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

quantum_source_sdk.PreparedSubmission.recover

recover() -> SubmissionReceipt

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

返回：SubmissionReceipt。

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

quantum_source_sdk.SchedulerClient.submit_job

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。

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

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

quantum_source_sdk.SchedulerClient.prepare_submissions

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

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

返回：PreparedBatch。

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

quantum_source_sdk.PreparedBatch

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 查询已发起的原提交。

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

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

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

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

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 继续等待。

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

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

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

quantum_source_sdk.SchedulerClient.wait_for_submission

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

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

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

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

quantum_source_sdk.SchedulerClient.get_job

get_job(job_id: str) -> JobRead

读取已有任务当前状态。

返回：JobRead。

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

quantum_source_sdk.SchedulerClient.get_submission

get_submission(preparation_id: str) -> SubmissionReceipt

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

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

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

quantum_source_sdk.SchedulerClient.list_jobs

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

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

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

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

quantum_source_sdk.SchedulerClient.list_submissions

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

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

返回：PaginatedSubmissions；记录位于 submissions。

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

取消与连接释放

quantum_source_sdk.SchedulerClient.cancel_job

cancel_job(job_id: str) -> None

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

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

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

quantum_source_sdk.SchedulerClient.cancel_submission

cancel_submission(preparation_id: str) -> SubmissionReceipt

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

返回：最新 SubmissionReceipt。

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

quantum_source_sdk.BaseClient.close

close() -> None

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

返回：None。

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

quantum_source_sdk.SchedulerClient.download_job_result

download_job_result(job: JobRead) -> UnifiedResult

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

返回：UnifiedResult。

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

quantum_source_sdk.SchedulerClient.download_job_output

download_job_output(job: JobRead) -> Any

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

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

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

quantum_source_sdk.SchedulerClient.download_job_calibration

download_job_calibration(job: JobRead) -> Any

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

返回：校准响应内容。

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

quantum_source_sdk.UnifiedResult

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

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

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

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

quantum_source_sdk.normalize_result_payload

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

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

返回：UnifiedResult。

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

报价与配额

quantum_source_sdk.QuoteSummary

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

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

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

源码：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

class BackendClassRead

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

返回：设备记录。

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

quantum_source_sdk.capabilities_from_backend

capabilities_from_backend(backend: BackendClassRead) -> BackendCapabilities

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

返回：BackendCapabilities。

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

quantum_source_sdk.get_capabilities

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

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

返回：BackendCapabilities。

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

quantum_source_sdk.fetch_capabilities

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

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

返回：BackendCapabilities。

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

quantum_source_sdk.list_backends

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

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

返回：list[str]。

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

quantum_source_sdk.capabilities_from_constraint_data

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

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

返回：BackendCapabilities。

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

quantum_source_sdk.BackendCapabilities

class BackendCapabilities

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

返回：只读能力模型。

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

quantum_source_sdk.BackendCapabilities.supports_execution_path

supports_execution_path(path: str) -> bool

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

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

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

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

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 提供对应的便捷查询。

返回：bool。

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

quantum_source_sdk.BackendCapabilities.supports_format

supports_format(name: str) -> bool

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

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

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

quantum_source_sdk.GateSpec

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

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

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

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

quantum_source_sdk.Topology

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。

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

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

quantum_source_qiskit · 服务与 Backend

服务和设备目录

quantum_source_qiskit.QuantumSourceService

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。

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

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

quantum_source_qiskit.QuantumSourceService.organizations

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

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

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

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

quantum_source_qiskit.QuantumSourceService.backends

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]]

读取并筛选设备目录。

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

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

quantum_source_qiskit.QuantumSourceService.return_backend

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。

返回：QuantumSourceBackend。

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

quantum_source_qiskit.QuantumSourceService.return_target

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

读取设备并构建 Qiskit Target。

返回：qiskit.transpiler.Target。

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

Backend 配置、编译与执行

quantum_source_qiskit.QuantumSourceBackend

class QuantumSourceBackend

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

返回：Qiskit BackendV2 兼容对象。

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

quantum_source_qiskit.QuantumSourceBackend.set_options

set_options(**fields: Any) -> None

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

返回：None。

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

quantum_source_qiskit.QuantumSourceBackend.transpile

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

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

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

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

quantum_source_qiskit.QuantumSourceBackend.validate_circuit

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

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

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

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

quantum_source_qiskit.QuantumSourceBackend.prepare

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 默认值。

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

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

quantum_source_qiskit.QuantumSourceBackend.run

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

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

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

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

quantum_source_qiskit.PreparedQuantumSourceJob

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

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

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

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

quantum_source_qiskit.QuantumSourceJob

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

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

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

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

quantum_source_qiskit.build_target

build_target(capabilities: BackendCapabilities) -> Target

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

返回：Target。

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

quantum_source_qiskit.export_circuit_to_qasm

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

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

返回：UTF-8 编码的 bytes。

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

quantum_source_qiskit.circuit_to_qasm

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

将 QuantumCircuit 导出为 OpenQASM 字符串。

返回：str。

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

quantum_source_qiskit · Sampler 与 Estimator

quantum_source_qiskit.QuantumSourceService.create_sampler

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 的导出别名。

返回：QuantumSourceSampler。

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

quantum_source_qiskit.QuantumSourceService.create_estimator

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 的导出别名。

返回：QuantumSourceEstimator。

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

quantum_source_qiskit.QuantumSourceSampler.prepare

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 参数绑定，为每条实际采样线路准备报价。

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

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

quantum_source_qiskit.QuantumSourceSampler.run

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 结构。

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

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

quantum_source_qiskit.QuantumSourceEstimator.prepare

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

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

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

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

quantum_source_qiskit.QuantumSourceEstimator.run

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

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

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

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

quantum_source_qiskit.PreparedQuantumSourcePrimitive

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

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

返回：QuantumSourcePrimitiveJob 或 PreparedSubmissionReceipt。

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

quantum_source_qiskit.QuantumSourcePrimitiveJob

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

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

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

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

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

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

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 并提交平台。

返回：QuantumSourceDevice。

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

quantum_source_pennylane.QuantumSourceDevice.prepare

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

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

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

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

quantum_source_pennylane.QuantumSourceDevice.execute

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

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

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

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

quantum_source_pennylane.QuantumSourceDevice.preprocess_transforms

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

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

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

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

quantum_source_pennylane.PreparedPennyLaneBatch

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=True 时返回原脚本测量结构；wait=False 保留可继续查询的批次对象。

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

quantum_source_pennylane.QuantumSourceDevice.supports_feature

supports_feature(name: str) -> bool

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

返回：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

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

刷新已提交任务的状态。

返回：最新任务对象。

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

quantum_source_pennylane.QuantumSourceDevice.cancel_job

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

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

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

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

quantum_source_pennylane.QuantumSourceDevice.close

close() -> None

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

返回：None。

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

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

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

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

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

返回：upload_endpoint_id 字符串。

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

quantum_source_sdk.JobPreparationCreate

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")

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

返回：JobPreparationCreate。

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

quantum_source_sdk.SchedulerClient.prepare_job

prepare_job(preparation: JobPreparationCreate) -> JobPreparationResponse

发起底层准备请求。

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

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

quantum_source_sdk.SchedulerClient.get_preparation_result

get_preparation_result(preparation_id: str) -> JobPreparationResultResponse

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

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

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

quantum_source_sdk.JobCreate

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)

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

返回：JobCreate。

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

quantum_source_sdk.SchedulerClient.create_job

create_job(job: JobCreate) -> JobRead | SubmissionReceipt

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

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

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

quantum_source_sdk.JobRead

class JobRead

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

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

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

quantum_source_sdk.SubmissionReceipt

class SubmissionReceipt

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

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

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

quantum_source_sdk.QueuedSubmission

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

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

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

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

异常与恢复

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

常用调用与教程入口

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

• Core：使用自己的 QASM 文件
• Core：设备配置
• Qiskit：Options 与 Target
• Qiskit：编译与物理布局
• Sampler 与 Estimator
• PennyLane：测量、shots 与梯度
• 底层提交协议

实现与验证索引

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