# 快速开始：运行第一个 Bell 实验

本页用 Core SDK 提交一段 OpenQASM 2 程序：连接平台、选择设备、准备报价，最后取得测量结果。下面的代码按顺序在同一个 Python 会话或 Notebook 内运行；如果你已经使用某个框架，可直接进入对应插件教程。

- [Qiskit 入门](qiskit.html)
- [PennyLane 入门](pennylane.html)

## 开始前需要什么

先完成安装与认证：使用 Python 3.12，安装本页配套 SDK，在环境中配置平台 API 根地址及平台 Client ID / Client Secret，或配置平台 SDK Key 文件路径。账号需要能使用所选设备，并具备报价所需的余额。

- [安装 SDK](install.html)
- [连接与认证](connection.html)

## 1. 连接平台并列出设备

下面使用环境凭据创建客户端。若已在认证页通过隐藏输入创建 scheduler，可直接沿用；使用同一份输入凭据新建客户端时，传入 creds=creds。

```python
import os
from quantum_source_sdk import SchedulerClient, JobSubmissionConfig

scheduler = SchedulerClient(base_url=os.environ["QUANTUM_SOURCE_API_URL"])
page = scheduler.management.list_backend_classes(limit=100)
for item in page.backend_classes:
    print(item.short_code, item.name, item.status)
```

SchedulerClient 是后续准备、提交和查询任务的入口；management 负责读取目录。list_backend_classes 返回分页对象，设备条目位于 page.backend_classes。此处仅显示三列，选择设备时使用 short_code。设备超过一页时，可继续读取下一页。

- [设备发现：读取下一页](backend-discovery.html#pagination)

该客户端默认使用 OPEN。需要 FULL 余额时，把创建行改为 SchedulerClient(base_url=os.environ["QUANTUM_SOURCE_API_URL"], currency="FULL")，再继续准备任务；scheduler.currency 可查看当前选择。

## 2. 选择设备和组织

```python
org_page = scheduler.management.list_user_organizations(limit=100)
for org in org_page.organizations:
    print(org.id, org.name)

backend_id = input("Backend short_code: ").strip()
organization_id = input("Organization ID: ").strip()
```

从目录选择目标设备，填写设备的 short_code 和上面列出的组织 ID。线路格式的转换由 SDK 和平台处理；本例通过 Core SDK 上传 OpenQASM 2 程序。需要了解门集、比特数、shots 或 mapping 等设备专属功能时，查看 Core 设备配置。

- [Core 设备配置：查询设备专属功能](capabilities-core.html)

## 3. 编写 Bell 程序

```python
qasm = b'''OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
'''

config = JobSubmissionConfig(
    backend_class_id=backend_id,
    organization_id=organization_id,
    name="first-bell",
    shots=128,
    input_format="openqasm2",
    configuration_data={"circuit_representation": "logical"},
)
```

H 门与 CX 门构成 Bell 线路，最后把两个量子比特测量到经典寄存器。b 前缀使 qasm 成为可上传的 bytes。shots=128 是本条任务的采样次数，0、1 是线路中的逻辑比特编号。JobSubmissionConfig 保存本次任务的配置。

## 4. 准备并查看报价

```python
prepared = scheduler.prepare_submission(config, file_content=qasm)
submission_id = prepared.preparation.id
print(prepared.quote)
```

prepare_submission 上传线路并请求平台报价，返回 PreparedSubmission。prepared.quote 用于核对设备、采样次数、金额、币种及有效期；submission_id 用于追踪这一条提交。查看报价后，在下一步确认执行。

金额和币种在 prepare 时固定，OPEN/FULL 独立记账。切换钱包时，使用对应客户端重新准备并查看新报价。

## 5. 确认本次实验

接受当前报价后执行本段。confirm 会提交实验，选择真机会使用设备资源；wait=False 让调用在提交后先返回。随后用 submission_id 查询进度和结果。

```python
receipt = prepared.confirm(wait=False)
```

## 6. 等待结果并读取计数

```python
job = scheduler.wait_for_submission(submission_id, timeout_seconds=300)
result = scheduler.download_job_result(job)
print(result.result_kind)
print(result.primary_value)
```

wait_for_submission 等待任务完成，download_job_result 下载并解析这次任务的计算结果。result_kind 表示结果类型，primary_value 是对应的结果数据。本例读取测量计数：字典的键是测量位串，值是该位串出现的次数。

如果等待超时，任务不会因此取消。稍后再次运行上面的结果查询代码，即可继续等待并读取同一个任务的结果，无需重新提交任务。

## 接下来可以做什么

- [了解每个提交参数及报价流程](job-submission.html)
- [筛选设备与读取目录](backend-discovery.html)
- [Core 的文件提交、批次与恢复](core.html)
- [下载按单元格组织的 Notebook](testing.html)

## 下载本页 Jupyter Notebook

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

[下载《快速开始》Notebook（.ipynb）](../../notebooks/sdk_user_guide_quickstart.ipynb)