Node.js 量子運算實戰：打造 IBM Q Experience API 客戶端

# 建立專案目錄
mkdir IBMQuantumExperience
cd IBMQuantumExperience

# 初始化 Node.js 專案
# 這會互動式地建立 package.json 檔案
npm init

# 安裝必要的相依套件
# request 套件用於發送 HTTP 請求
npm install request

/**
 * IBM Quantum Experience Node.js 客戶端
 * 
 * 這個模組提供與 IBM Q Experience REST API 互動的功能
 * 包含身份驗證、裝置查詢與量子實驗提交
 * 
 * @module IBMQuantumExperience
 * @author 玄貓（BlackCat）
 */

// 引入 HTTP 請求函式庫
// request 套件提供簡潔的 API 來發送各種 HTTP 請求
const request = require('request');

// 內部狀態變數
// 使用底線前綴表示這些是私有變數，不應該被外部直接存取
let _config = null;           // 儲存配置資訊
let _accessToken = null;      // 儲存存取令牌
let _userId = null;           // 儲存使用者 ID
const _userAgent = 'qiskit-api-node';  // 客戶端識別字串

// 預設的 HTTP 請求標頭
// 所有 API 請求都會包含這個標頭來識別客戶端應用程式
const _defaultHeaders = {
  'x-qx-client-application': _userAgent
};

/**
 * 使用 API Token 進行身份驗證
 * 
 * 這個函數向 IBM Q Experience API 發送登入請求
 * 使用 API Token 換取臨時的存取令牌
 * 
 * @returns {Promise} 解析為使用者資訊的 Promise
 * @private
 */
function loginWithToken() {
  // 準備 HTTP POST 請求的選項
  const options = {
    // 登入端點的完整 URL
    url: _config.url + '/users/loginWithToken',
    // 表單資料，包含 API Token
    form: {
      'apiToken': _config.APItoken
    }
  };

  // 回傳一個 Promise 來處理非同步操作
  return new Promise(function(resolve, reject) {
    // 發送 POST 請求進行登入
    request.post(options, function(err, response, body) {
      // 檢查是否有錯誤發生
      if (err) {
        // 如果有錯誤，拒絕 Promise 並傳遞錯誤物件
        reject(err);
      } else {
        // 解析回應的 JSON 字串
        const json = JSON.parse(body);
        
        // 儲存存取令牌與使用者 ID
        // 這些資訊會在後續的 API 請求中使用
        _accessToken = json.id;
        _userId = json.userId;
        
        // 如果啟用除錯模式，輸出日誌
        if (_config.debug) {
          console.log(`已取得使用者 ID: ${_userId}`);
          console.log(`存取令牌: ${_accessToken}`);
        }
        
        // 解析 Promise 並回傳使用者資訊
        resolve(json);
      }
    });
  });
}

/**
 * 取得可用的後端裝置列表
 * 
 * 查詢 IBM Q Experience 平台上所有可用的量子處理器與模擬器
 * 包含裝置名稱、狀態、量子位元數等資訊
 * 
 * @returns {Promise} 解析為裝置列表陣列的 Promise
 */
function getBackends() {
  // 準備 HTTP GET 請求的選項
  const options = {
    // Backends 端點的完整 URL，包含存取令牌
    url: `${_config.url}/Backends?access_token=${_accessToken}`,
    // 請求標頭
    headers: _defaultHeaders
  };

  return new Promise(function(resolve, reject) {
    // 發送 GET 請求查詢裝置列表
    request.get(options, function(err, response, body) {
      if (err) {
        reject(err);
      } else {
        // 解析並回傳裝置列表
        resolve(JSON.parse(body));
      }
    });
  });
}

/**
 * 取得特定裝置的校準資料
 * 
 * 量子處理器需要定期校準以維持運作品質
 * 這個方法回傳指定裝置的最新校準資料
 * 包含閘操作的錯誤率、讀取錯誤等資訊
 * 
 * @param {string} deviceName - 裝置名稱，例如 'ibmqx4'
 * @returns {Promise} 解析為校準資料物件的 Promise
 */
function getCalibration(deviceName) {
  const options = {
    url: `${_config.url}/Backends/${deviceName}/calibration?access_token=${_accessToken}`,
    headers: _defaultHeaders
  };

  return new Promise(function(resolve, reject) {
    request.get(options, function(err, response, body) {
      if (err) {
        reject(err);
      } else {
        resolve(JSON.parse(body));
      }
    });
  });
}

/**
 * 取得特定裝置的參數資訊
 * 
 * 回傳裝置的硬體規格與限制
 * 例如量子位元數、連接拓撲、支援的閘操作等
 * 
 * @param {string} deviceName - 裝置名稱
 * @returns {Promise} 解析為參數物件的 Promise
 */
function getParameters(deviceName) {
  const options = {
    url: `${_config.url}/Backends/${deviceName}/parameters?access_token=${_accessToken}`,
    headers: _defaultHeaders
  };

  return new Promise(function(resolve, reject) {
    request.get(options, function(err, response, body) {
      if (err) {
        reject(err);
      } else {
        resolve(JSON.parse(body));
      }
    });
  });
}

/**
 * 提交量子實驗到指定裝置
 * 
 * 這是客戶端的核心功能，用於提交 QASM 程式碼到量子處理器執行
 * 
 * @param {string} name - 實驗名稱
 * @param {string} qasm - QASM 量子電路程式碼
 * @param {number} shots - 執行次數（重複測量以提高準確性）
 * @param {string} device - 目標裝置名稱
 * @returns {Promise} 解析為任務資訊的 Promise
 */
function runExperiment(name, qasm, shots, device) {
  // 準備實驗的 JSON 負載
  const payload = {
    // QASM 程式碼陣列，可以包含多個電路
    qasms: [{
      qasm: qasm
    }],
    // 執行次數
    shots: shots,
    // 目標後端裝置
    backend: {
      name: device
    },
    // 最大允許使用的積分
    maxCredits: 3
  };

  const options = {
    url: `${_config.url}/Jobs?access_token=${_accessToken}`,
    headers: _defaultHeaders,
    // 將 payload 物件轉換為 JSON 字串
    body: JSON.stringify(payload),
    // 設定內容類型為 JSON
    headers: {
      ..._defaultHeaders,
      'Content-Type': 'application/json'
    }
  };

  return new Promise(function(resolve, reject) {
    // 使用 POST 方法提交實驗
    request.post(options, function(err, response, body) {
      if (err) {
        reject(err);
      } else {
        const result = JSON.parse(body);
        
        if (_config.debug) {
          console.log(`實驗已提交: ${name}`);
          console.log(`任務 ID: ${result.id}`);
        }
        
        resolve(result);
      }
    });
  });
}

/**
 * 模組匯出的公開 API
 * 
 * 這些方法可以被外部程式碼呼叫
 */
module.exports = {
  /**
   * 初始化客戶端
   * 
   * @param {Object} config - 配置物件
   * @param {string} config.APItoken - IBM Q Experience API Token
   * @param {string} config.url - API 基礎 URL
   * @param {boolean} config.debug - 是否啟用除錯模式
   * @returns {Promise} 解析為使用者資訊的 Promise
   */
  init: function(config) {
    _config = config;
    return loginWithToken();
  },
  
  // 匯出其他 API 方法
  getBackends: getBackends,
  getCalibration: getCalibration,
  getParameters: getParameters,
  runExperiment: runExperiment
};

/**
 * IBM Quantum Experience 客戶端使用範例
 * 
 * 展示如何使用 async/await 語法來操作量子運算 API
 */

// 引入我們建立的客戶端模組
const qx = require('./IBMQuantumExperience');

// 配置物件
// 包含 API Token 與其他必要的設定
const config = {
  // 從 IBM Q Experience 網站取得的 API Token
  // 這是一個敏感資訊，實務上應該從環境變數或配置檔讀取
  APItoken: 'YOUR_API_TOKEN_HERE',
  
  // IBM Q Experience API 的基礎 URL
  url: 'https://quantumexperience.ng.bluemix.net/api',
  
  // 啟用除錯模式，會輸出詳細的日誌資訊
  debug: true,
  
  // 以下參數為企業客戶使用，一般使用者可以省略
  hub: 'MY_HUB',
  group: 'MY_GROUP',
  project: 'MY_PROJECT'
};

/**
 * 測試取得後端裝置列表
 * 
 * 這個函數展示如何查詢可用的量子處理器與模擬器
 */
async function testGetBackends() {
  try {
    // 初始化客戶端並進行身份驗證
    // await 關鍵字會等待 Promise 解析完成
    await qx.init(config);
    console.log('身份驗證成功\n');
    
    // 取得可用的後端裝置列表
    const backends = await qx.getBackends();
    
    // 顯示裝置資訊
    console.log('=== 可用的量子裝置 ===\n');
    backends.forEach(backend => {
      console.log(`裝置名稱: ${backend.name}`);
      console.log(`狀態: ${backend.status}`);
      console.log(`量子位元數: ${backend.nQubits}`);
      console.log(`是否模擬器: ${backend.simulator}`);
      console.log('---');
    });
    
  } catch (error) {
    // 統一的錯誤處理
    console.error('操作失敗:', error.message);
  }
}

/**
 * 測試取得裝置的詳細資訊
 * 
 * 展示如何查詢特定裝置的校準資料與參數
 */
async function testDeviceInfo() {
  try {
    await qx.init(config);
    
    // 指定要查詢的裝置名稱
    const deviceName = 'ibmqx4';
    
    // 同時取得校準資料與參數
    // Promise.all 可以平行執行多個非同步操作
    const [calibration, parameters] = await Promise.all([
      qx.getCalibration(deviceName),
      qx.getParameters(deviceName)
    ]);
    
    console.log(`=== ${deviceName} 裝置資訊 ===\n`);
    
    console.log('校準資料:');
    console.log(JSON.stringify(calibration, null, 2));
    
    console.log('\n參數資訊:');
    console.log(JSON.stringify(parameters, null, 2));
    
  } catch (error) {
    console.error('查詢失敗:', error.message);
  }
}

/**
 * 測試提交量子實驗
 * 
 * 展示完整的實驗提交流程
 * 包含 QASM 程式碼的準備與實驗參數的設定
 */
async function testRunExperiment() {
  try {
    await qx.init(config);
    
    // 實驗名稱
    const experimentName = 'Node.js 量子實驗 #1';
    
    // QASM 量子電路程式碼
    // 這段程式碼定義了一個簡單的量子電路
    // 包含量子閘操作與測量指令
    const qasmCode = `
// QASM 2.0 量子組合語言
// 引入標準量子閘函式庫
include "qelib1.inc";

// 宣告 5 個量子位元的暫存器
qreg q[5];

// 宣告 5 個古典位元的暫存器用於儲存測量結果
creg c[5];

// 對第 0 個量子位元應用一系列的 U 閘
// U 閘是通用的單量子位元旋轉閘
u2(-4*pi/3, 2*pi) q[0];
u2(-3*pi/2, 2*pi) q[0];
u3(-pi, 0, -pi) q[0];
u3(-pi, 0, -pi/2) q[0];
u2(pi, -pi/2) q[0];
u3(-pi, 0, -pi/2) q[0];

// 測量所有量子位元並將結果儲存到古典暫存器
measure q -> c;
`;
    
    // 執行次數
    // 量子測量具有機率性，需要多次執行來統計結果分布
    const shots = 1024;
    
    // 目標裝置
    // 可以選擇真實的量子處理器或模擬器
    const targetDevice = 'ibmqx4';
    
    console.log(`準備提交實驗: ${experimentName}`);
    console.log(`目標裝置: ${targetDevice}`);
    console.log(`執行次數: ${shots}\n`);
    
    // 提交實驗
    const result = await qx.runExperiment(
      experimentName,
      qasmCode,
      shots,
      targetDevice
    );
    
    console.log('實驗提交成功！');
    console.log(`任務 ID: ${result.id}`);
    console.log(`狀態: ${result.status}`);
    
    // 實務上可以使用任務 ID 來查詢執行結果
    // 由於量子計算需要時間，通常需要輪詢或使用 WebSocket 來取得結果
    
  } catch (error) {
    console.error('實驗提交失敗:', error.message);
  }
}

// 執行測試函數
// 可以根據需要選擇要執行的測試
testGetBackends();
// testDeviceInfo();
// testRunExperiment();