2024年11月18日玄貓（BlackCat）

IBM Q Experience REST API 深度解析

本文深入解析鮮為人知的 IBM Q Experience REST API，探討其認證機制、後端系統資訊取得、校準引數、佇列狀態、任務列表等核心功能，並提供程式碼範例及詳細的引數說明，讓開發者能更有效地運用此 API 進行量子程式設計與遠端存取。

量子計算 API

REST API IBM Q Experience 量子計算 QASM API Token 存取權杖

現今量子計算領域的 Python SDKs，如 QISKit 和 IBMQExperience，底層皆仰賴 IBM Q Experience 提供的 REST API 進行遠端操作。理解此 API 的運作機制，有助於開發者更深入地掌握量子程式設計的流程，並能更有效地控制及監控實驗執行。本文將詳細介紹此 REST API 的各項功能，包含認證流程、後端系統資訊、校準引數、佇列狀態以及任務列表等，並提供程式碼範例及說明，以利開發者快速上手。透過這些資訊，開發者將能更精確地控制實驗引數，並更有效率地分析實驗結果，進而提升量子程式開發的效率和效能。

遠端存取IBM Q Experience：REST API深度解析

IBM Q Experience提供了一個相對鮮為人知的REST API，用於處理幕後的所有遠端通訊。目前的Python SDKs，如QISKit和IBMQExperience，均使用此API進行量子程式設計與遠端存取。

認證機制

在呼叫任何REST API之前，必須先取得存取權杖（Access Token）。這是進一步呼叫其他API的鑰匙。注意，存取權杖與API權杖（API Token）不同，後者用於執行Python中的量子程式。

取得存取權杖的兩種方法

使用API權杖：登入IBM Q Experience控制檯，按照指示取得API權杖。
- HTTP方法：POST
- URL：https://quantumexperience.ng.bluemix.net/api/users/loginWithToken
- 負載：{“apiToken”: “YOUR_API_TOKEN”}
使用帳戶使用者名稱和密碼：透過REST API進行認證。
- HTTP方法：POST
- URL：https://quantumexperience.ng.bluemix.net/api/users/login
- 負載：{“email”: “USER-NAME”, “password”: “YOUR-PASSWORD”}

兩種方法的回應均包含存取權杖、存活時間（ttl）及使用者ID。

回應範例

{
  "id": "ACCESS_TOKEN",
  "ttl": 1209600,
  "created": "2018-04-15T20:21:03.204Z",
  "userId": "USER-ID"
}

列出可用的後端系統

此呼叫傳回IBM Q Experience中所有可用後端系統和模擬器的JSON列表。

HTTP方法：GET
URL：https://quantumexperience.ng.bluemix.net/api/Backends?access_token=ACCESS-TOKEN

請求引數

名稱	值
access_token	您的帳戶存取權杖

HTTP標頭

名稱	值
x-qx-client-application	預設為qiskit-api-py

回應範例（部分）

[{
  "name": "ibmqx2",
  "version": "1",
  "status": "on",
  "serialNumber": "Real5Qv2",
  "description": "5 transmon bowtie",
  "basisGates": "u1,u2,u3,cx,id",
  "onlineDate": "2017-01-10T12:00:00+08:00",
  "chipName": "Sparrow",
  "id": "28147a578bdc88ec8087af46ede526e1",
  "topologyId": "250e969c6b9e68aa2a045ffbceb3ac33",
  "url": "https://ibm.biz/qiskit-ibmqx2",
  "simulator": false,
  "nQubits": 5,
  "couplingMap": [
    [0, 1],
    [0, 2],
    [1, 2],
    [3, 2],
    [3, 4],
    [4, 2]
  ]
},...]

可用後端系統回應鍵值說明

鍵值	說明
name	用於執行程式碼的處理器名稱ID。
version	可能用於追蹤處理器變更的字串或正整數。
description	對硬體的描述，例如「5 transmon bowtie」或「16 transmon 2x8 ladder」。
basisGates	處理器的物理量子位閘，是建構更複雜邏輯閘的基礎。
nQubits	處理器使用的量子位數。
couplingMap	定義個體量子位元之間的互動作用，同時保持量子相干性，用於簡化量子電路。

詳細解說

basisGates：基礎閘包括u1、u2、u3、cx和id等基本操作，用於實作更複雜的量子邏輯運算。
couplingMap：耦合對映定義了哪些量子位元可以直接相互作用，這對於設計和最佳化量子演算法至關重要。

取得特定處理器的校準資訊

此API呼叫傳回IBM Q Experience中特定處理器的校準引數JSON列表。這些引數在IBM QX後端資訊網站中有詳細說明。

請求資訊

HTTP方法： GET
URL： https://quantumexperience.ng.bluemix.net/api/Backends/NAME/calibration?access_token=ACCESS-TOKEN

請求引數

名稱	值
access_token	您的帳戶存取令牌

HTTP標頭

名稱	值
x-qx-client-application	預設為qiskit-api-py（官方客戶端的預設值，但可以是任何值）

回應範例

量子位元（Qubits）對錯誤和環境噪聲非常敏感。校準資訊提供了處理器內部量子位元品質的概覽。清單3-2顯示了ibmqx4校準引數的簡化回應。其中一些最值得注意的引數包括：

gateError： 在給定時間內，量子位元閘操作錯誤率。
readoutError： 在給定時間內，量子位元讀取操作錯誤率。

清單3-2：ibmqx4校準引數的簡化回應

{
  "lastUpdateDate": "2018-04-15T10:47:03+08:00",
  "qubits": [
    {
      "gateError": {
        "date": "2018-04-15T10:47:03Z",
        "value": 0.0012019552727863259
      },
      "name": "Q0",
      "readoutError": {
        "date": "2018-04-15T10:47:03Z",
        "value": 0.049
      }
    },
    ...
  ],
  "multiQubitGates": [
    {
      "qubits": [1, 0],
      "type": "CX",
      "gateError": {
        "date": "2018-04-15T10:47:03Z",
        "value": 0.03024023736391171
      },
      "name": "CX1_0"
    },
    ...
  ]
}

程式碼解析：

上述JSON回應中包含了多個重要資訊，以下是逐項解析：

lastUpdateDate： 表示校準資料的最後更新日期和時間。
qubits： 包含每個量子位元的詳細資訊，如名稱、閘錯誤率和讀取錯誤率。
- gateError： 表示特定量子位元的閘操作錯誤率。
- readoutError： 表示特定量子位元的讀取操作錯誤率。
multiQubitGates： 描述多量子位元閘操作的資訊，包括參與的量子位元、閘型別和錯誤率。

取得後端引數

此API呼叫傳回IBM Q Experience中特定處理器的後端引數JSON列表。這些引數包括：

量子位元冷卻溫度（單位：開爾文）： 例如，ibmqx4的溫度為0.021 K，即-459.6 °F或-273.1 °C。
緩衝時間（單位：奈秒）：
閘時間（單位：奈秒）：
其他量子規格詳見後端資訊網站。

請求資訊

HTTP方法： GET
URL： https://quantumexperience.ng.bluemix.net/api/Backends/NAME/parameters?access_token=ACCESS-TOKEN

請求引數

名稱	值
access_token	您的帳戶存取令牌

HTTP標頭

名稱	值
x-qx-client-application	預設為qiskit-api-py

回應範例

清單3-3顯示了ibmqx4引數的簡化JSON回應。

{
  "lastUpdateDate": "2018-04-15T10:47:03+08:00",
  "fridgeParameters": {
    "cooldownDate": "2017-09-07",
    "Temperature": {
      "date": "2018-04-15T10:47:03Z",
      "value": 0.021,
      "unit": "K"
    }
  },
  "qubits": [
    {
      "name": "Q0",
      "buffer": {
        "date": "2018-04-15T10:47:03Z",
        "value": 10,
        "unit": "ns"
      },
      "gateTime": {
        "date": "2018-04-15T10:47:03Z",
        "value": 50,
        "unit": "ns"
      },
      ...
    }
  ]
}

程式碼解析：

fridgeParameters： 提供有關冰箱引數的資訊，包括冷卻日期和溫度。
- Temperature： 表示當前的溫度，單位為開爾文。
qubits： 列出每個量子位元的詳細資訊，包括名稱、緩衝時間和閘時間。
- buffer： 緩衝時間的設定，單位為奈秒。
- gateTime： 閘操作的時間，單位為奈秒。

取得處理器佇列狀態

此API呼叫傳回特定量子處理器事件佇列的狀態。

請求資訊

HTTP方法： GET
URL： https://quantumexperience.ng.bluemix.net/api/Backends/NAME/queue/status

回應範例

例如，要取得ibmqx4的事件佇列狀態，可以在瀏覽器中輸入以下URL： https://quantumexperience.ng.bluemix.net/api/Backends/ibmqx4/queue/status

回應格式如下：

{"state":true,"status":"active","lengthQueue":0}

其中：

state： 處理器的狀態。如果存活，則為true，否則為false。
status： 執行佇列的狀態，可以是active或busy。
lengthQueue： 執行佇列的大小或等待執行的模擬數量。

列出執行佇列中的任務

此API呼叫傳回處理器執行佇列中的任務列表。

請求資訊

HTTP方法： GET
URL： https://quantumexperience.ng.bluemix.net/api/Jobs?access_token=ACCESS-TOKEN&filter=FILTER

請求引數

名稱	值
access_token	您的帳戶存取令牌
filter	JSON格式的結果大小提示。例如，{“limit”:2}傳回最多兩個條目

HTTP標頭

名稱	值
x-qx-client-application	預設為qiskit-api-py

回應範例

清單3-4顯示了此API呼叫的回應格式。資訊似乎是實驗執行的歷史記錄，包含狀態、日期、結果、程式碼、校準等資訊。

[
  {
    "qasms": [
      {
        "qasm": "...",
        "status": "DONE",
        "executionId": "331f15a5eed1a4f72aa2fb4d96c75380",
        "result": {
          "date": "2018-04-05T14:25:37.948Z",
          "data": {
            ...
          }
        }
      }
    ]
  }
]

程式碼解析：

qasms： 列出與任務相關的QASM（Quantum Assembly Language）資訊，包括狀態、執行ID和結果。
- qasm： QASM程式碼內容。
- status： 任務的狀態，例如DONE表示已完成。
- executionId： 任務的執行ID，用於識別特定的執行例項。
- result： 包含任務執行的結果資料，包括日期和具體資料。

IBM Q Experience API 介面操作

IBM Q Experience 提供了一系列的 REST API，讓使用者能夠遠端執行量子實驗、管理帳戶資訊以及查詢實驗結果。以下將詳細介紹如何使用這些 API 進行操作。

認證與授權

在使用 IBM Q Experience API 之前，首先需要進行認證以取得 access_token。認證方式可以透過 API token 或使用者密碼進行。

HTTP 方法：POST

URL：https://quantumexperience.ng.bluemix.net/api/users/loginWithToken

取得執行結果

此 API 用於取得先前提交的量子實驗執行結果。

HTTP 方法：GET

URL：https://quantumexperience.ng.bluemix.net/api/Jobs?access_token=ACCESS-TOKEN

回傳範例：

{
  "jobs": [
    {
      "result": {
        "creg_labels": "c[5]",
        "additionalData": {
          "seed": 348582688
        },
        "time": 0.0166247,
        "counts": {
          "11100": 754,
          "01100": 270
        }
      }
    }
  ]
}

內容解密：

creg_labels：表示經典暫存器的標籤。
additionalData：包含額外的實驗資料，如亂數種子 seed。
time：實驗執行的時間。
counts：測量結果的統計次數。

取得帳戶點數資訊

此 API 用於查詢當前帳戶的點數餘額。

HTTP 方法：GET

URL：https://quantumexperience.ng.bluemix.net/api/users/USER-ID?access_token=ACCESS-TOKEN

回傳範例：

{
  "credit": {
    "promotional": 0,
    "remaining": 150,
    "promotionalCodesUsed": [],
    "lastRefill": "2018-04-12T14:05:09.136Z",
    "maxUserType": 150
  }
}

內容解密：

promotional：促銷點數。
remaining：剩餘點數。
promotionalCodesUsed：已使用的促銷碼列表。
lastRefill：上次點數補充的時間。
maxUserType：使用者型別的最大點數限制。

列出使用者實驗

此 API 用於列出特定使用者 ID 的所有實驗。

HTTP 方法：GET

URL：https://quantumexperience.ng.bluemix.net/api/users/USER-ID/codes/latest?access_token=ACCESS-TOKEN&includeExecutions=true

回傳範例：

{
  "total": 17,
  "count": 17,
  "codes": [
    {
      "type": "Algorithm",
      "name": "3Q GHZ State YXY-Measurement 1",
      "jsonQASM": { ... },
      "creationDate": "2018-04-14T19:09:51.382Z"
    }
  ]
}

內容解密：

total 和 count：實驗總數。
codes：包含所有實驗的詳細資訊列表。
type 和 name：實驗的型別和名稱。
jsonQASM：實驗的 QASM 程式碼表示。
creationDate：實驗建立的時間。

執行實驗

此 API 用於在 IBM Q Experience 上遠端執行量子實驗。

HTTP 方法：POST

URL：https://quantumexperience.ng.bluemix.net/api/codes/execute?access_token=ACCESS-TOKEN&shots=SHOTS&deviceRunType=RUN-TYPE

請求主體範例：

{
  "name": "Bell State XW Measurement",
  "codeType": "QASM2",
  "qasm": "IBMQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nh q[0];\ns q[1];\nh q[1];\nt q[1];\nh q[1];\nmeasure q[0] -> c[0];\nmeasure q[1] -> c[1];"
}

內容解密：

name：實驗的名稱。
codeType：程式碼型別，固定為 QASM2。
qasm：單行格式的 QASM 程式碼，需包含換行符號 \n。

提交到模擬器

使用以下請求引數提交到模擬器：

access_token=ACCESS_TOKEN
shots=1
deviceRunType=simulator

驗證回應程式碼是否為 200（OK），並檢查實驗是否已在 Q Experience 控制檯中記錄。