麦普量子

Name: 麦普量子
Author: manalejandro

作者：manalejandro2 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

CUDA Quantum MCP Server

一个全面的模型上下文协议（MCP）服务器，使用NVIDIA的CUDA Quantum框架提供量子计算能力，并支持GPU加速。

🚀 特性

量子电路构建

创建量子内核：使用参数化电路
应用量子门：(H, X, Y, Z, CNOT, 旋转门等)
构建常见电路：(贝尔对，GHZ态，QFT)
可视化电路：文本格式
管理量子寄存器和量子比特操作

量子执行

采样量子电路：测量统计
计算哈密顿量期望值
获取量子态向量：幅度分析
运行量子算法：自定义返回值
变分优化：用于量子机器学习

硬件后端集成

多个模拟器：CPU、GPU（cuQuantum）、张量网络
量子硬件：IonQ、Quantinuum、Quantum Machines等
GPU加速：NVIDIA CUDA支持
目标配置：后端特定参数
远程量子处理器连接测试

高级功能

Python桥接：无缝CUDA Quantum集成
异步执行：长时间运行的量子任务
错误缓解和噪声建模
多GPU支持：大规模模拟
全面的日志记录和调试工具

📦 安装

先决条件

Node.js 18+ 和 npm
Python 3.8+ 和 pip
NVIDIA GPU（可选，用于GPU加速）
CUDA Toolkit（可选，用于GPU后端）

安装CUDA Quantum

# 安装CUDA Quantum Python包
pip install cudaq

# 对于GPU支持，请确保CUDA已正确安装
nvidia-smi  # 检查NVIDIA驱动
nvcc --version  # 检查CUDA编译器

安装MCP Server

# 克隆仓库
git clone <repository-url>
cd mcp-quantum

# 安装Node.js依赖
npm install

# 安装Python依赖
npm run python-setup

# 构建TypeScript
npm run build

环境配置

复制示例环境文件并进行配置：

cp .env.example .env

编辑.env文件以设置您的配置：

# 服务器配置
SERVER_PORT=3000
NODE_ENV=production

# CUDA Quantum配置
CUDAQ_PYTHON_PATH=/usr/local/bin/python3
CUDAQ_DEFAULT_TARGET=qpp-cpu
CUDAQ_LOG_LEVEL=info

# Python桥接超时（毫秒）
# 默认：300000（5分钟）
# 对于复杂操作或较慢的硬件，增加此值
PYTHON_TIMEOUT=300000

# GPU配置
CUDA_VISIBLE_DEVICES=0
CUDAQ_ENABLE_GPU=true

# 硬件提供商API密钥（可选）
QUANTUM_MACHINES_API_KEY=your_api_key_here
IONQ_API_KEY=your_api_key_here

🏃‍♂️ 快速开始

1. 启动MCP Server

npm start

2. 通过MCP客户端连接

服务器使用stdio传输进行MCP通信：

# 例如通过Claude Desktop连接
# 添加到您的Claude Desktop配置中

3. 基本量子电路示例

// 创建贝尔对电路
await mcp.callTool('create_quantum_kernel', {
  name: 'bell_pair',
  num_qubits: 2
});

// 在量子比特0上应用Hadamard门
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'bell_pair',
  gate_name: 'h',
  qubits: [0]
});

// 应用CNOT门（受控-X）
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'bell_pair', 
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

// 采样电路
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'bell_pair',
  shots: 1000
});

🔧 可用工具

量子电路工具

`create_quantum_kernel`

创建具有指定量子比特和参数的新量子内核。

{
  "name": "my_kernel",
  "num_qubits": 4,
  "parameters": [
    {"name": "theta", "type": "float"},
    {"name": "angles", "type": "list[float]"}
  ]
}

`apply_quantum_gate`

将量子门应用于特定量子比特，可选控制量子比特。

{
  "kernel_name": "my_kernel",
  "gate_name": "rx",
  "qubits": [0],
  "parameters": [1.57],
  "controls": [],
  "adjoint": false
}

支持的门：

单量子比特：h, x, y, z, s, t, rx, ry, rz
双量子比特：cx (CNOT), cy, cz, swap
多量子比特：ccx (Toffoli), cswap (Fredkin)

`create_common_circuit`

生成常用的量子电路。

{
  "circuit_type": "ghz_state",
  "name": "ghz_3",
  "num_qubits": 3
}

可用电路：

bell_pair：最大纠缠两量子比特状态
ghz_state：Greenberger-Horne-Zeilinger态
quantum_fourier_transform：QFT实现
hadamard_test：Hadamard测试电路

量子执行工具

`sample_quantum_circuit`

执行量子电路并采样测量结果。

{
  "kernel_name": "bell_pair",
  "shots": 1000,
  "target": "qpp-gpu"
}

`observe_hamiltonian`

计算哈密顿量算子的期望值。

{
  "kernel_name": "my_kernel",
  "hamiltonian_terms": [
    {
      "paulis": ["Z", "Z"],
      "qubits": [0, 1],
      "coefficient": {"real": 1.0, "imag": 0.0}
    }
  ],
  "shots": 1000
}

`get_quantum_state`

从电路中检索量子态向量。

{
  "kernel_name": "my_kernel",
  "format": "amplitudes"
}

硬件后端工具

`set_quantum_target`

配置量子执行目标。

{
  "target": "qpp-gpu",
  "configuration": {
    "shots": 1000,
    "optimization_level": 2
  }
}

可用目标：

模拟器：

qpp-cpu：CPU状态向量模拟器
qpp-gpu：GPU加速模拟器（cuQuantum）
density-matrix-cpu：密度矩阵模拟器
tensor-network：张量网络模拟器

硬件提供商：

ionq：IonQ量子处理器
quantinuum：Quantinuum H系列
quantum_machines：Quantum Machines平台
infleqtion：Infleqtion量子处理器

`configure_gpu_acceleration`

启用/禁用量子模拟的GPU加速。

{
  "enable": true,
  "device_id": 0,
  "memory_limit": 8.0,
  "target": "qpp-gpu"
}

🧪 示例

示例1：量子隐形传态电路

// 创建量子隐形传态电路
await mcp.callTool('create_quantum_kernel', {
  name: 'teleportation',
  num_qubits: 3
});

// 准备贝尔对（量子比特1,2）
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'h',
  qubits: [1]
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'x',
  qubits: [2],
  controls: [1]
});

// 量子隐形传态协议（量子比特0 -> 量子比特2）
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'h',
  qubits: [0]
});

// 采样结果
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'teleportation',
  shots: 1000
});

示例2：变分量子特征值求解器（VQE）

// 创建参数化的Ansatz
await mcp.callTool('create_quantum_kernel', {
  name: 'vqe_ansatz',
  num_qubits: 2,
  parameters: [
    {"name": "theta1", "type": "float"},
    {"name": "theta2", "type": "float"}
  ]
});

// 构建Ansatz电路
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'vqe_ansatz',
  gate_name: 'ry',
  qubits: [0],
  parameters: ['theta1']  // 参数引用
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'vqe_ansatz',
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

// 定义H2分子哈密顿量
const h2_hamiltonian = [
  {
    "paulis": ["Z", "I"],
    "qubits": [0, 1],
    "coefficient": {"real": -1.0523732, "imag": 0.0}
  },
  {
    "paulis": ["I", "Z"],
    "qubits": [0, 1], 
    "coefficient": {"real": -1.0523732, "imag": 0.0}
  },
  {
    "paulis": ["Z", "Z"],
    "qubits": [0, 1],
    "coefficient": {"real": -0.39793742, "imag": 0.0}
  }
];

// 计算期望值
await mcp.callTool('observe_hamiltonian', {
  kernel_name: 'vqe_ansatz',
  hamiltonian_terms: h2_hamiltonian,
  parameters: {"theta1": 0.5, "theta2": 1.2}
});

示例3：GPU加速模拟

// 配置GPU加速
await mcp.callTool('configure_gpu_acceleration', {
  enable: true,
  device_id: 0,
  target: 'qpp-gpu'
});

// 创建大型量子电路
await mcp.callTool('create_quantum_kernel', {
  name: 'large_circuit',
  num_qubits: 20
});

// 应用随机电路
for (let i = 0; i < 20; i++) {
  await mcp.callTool('apply_quantum_gate', {
    kernel_name: 'large_circuit',
    gate_name: 'h',
    qubits: [i]
  });
}

// 添加纠缠门
for (let i = 0; i < 19; i++) {
  await mcp.callTool('apply_quantum_gate', {
    kernel_name: 'large_circuit',
    gate_name: 'x',
    qubits: [i + 1],
    controls: [i]
  });
}

// 使用GPU加速采样
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'large_circuit',
  shots: 10000,
  target: 'qpp-gpu'
});

🔌 硬件提供商设置

IonQ配置

await mcp.callTool('set_quantum_target', {
  target: 'ionq',
  configuration: {
    api_key: process.env.IONQ_API_KEY,
    backend: 'simulator',  // 或 'qpu'
    shots: 1000
  }
});

Quantinuum设置

await mcp.callTool('set_quantum_target', {
  target: 'quantinuum',
  configuration: {
    api_key: process.env.QUANTINUUM_API_KEY,
    device: 'H1-1E',  // 或其他可用设备
    shots: 1000
  }
});

Quantum Machines设置

await mcp.callTool('set_quantum_target', {
  target: 'quantum_machines',
  configuration: {
    api_key: process.env.QUANTUM_MACHINES_API_KEY,
    url: 'https://api.quantum-machines.com',
    executor: 'qpu'  // 或 'simulator'
  }
});

🐛 故障排除

常见问题

CUDA Quantum导入错误

Error: CUDA Quantum不可用
解决方案：pip install cudaq

GPU未检测到

Error: 未找到CUDA设备
解决方案：
1. 检查nvidia-smi输出
2. 安装NVIDIA驱动
3. 设置CUDA_VISIBLE_DEVICES=0

Python桥接超时

Error: Python命令超时Xms
解决方案：
1. 使用环境变量增加超时时间：
   export PYTHON_TIMEOUT=600000  # 10分钟，单位为毫秒
2. 检查Python路径在.env中：
   CUDAQ_PYTHON_PATH=/usr/local/bin/python3
3. 确保CUDA Quantum已正确安装：
   python3 -c "import cudaq; print(cudaq.__version__)"
4. 检查日志中的Python进程错误

注意：默认超时时间为300,000ms（5分钟）。复杂的量子操作或较慢的硬件可能需要通过PYTHON_TIMEOUT环境变量增加此值。

调试模式

启用调试日志记录：

export LOG_LEVEL=debug
npm start

测试连接

// 测试平台可用性
await mcp.callTool('get_platform_info');

// 测试后端连接
await mcp.callTool('test_backend_connectivity', {
  backend: 'qpp-gpu'
});

🧪 测试

运行测试套件：

# 单元测试
npm test

# 集成测试
npm run test:integration

# 覆盖报告
npm run test:coverage

📚 API参考

MCP工具模式

所有工具遵循MCP（模型上下文协议）规范：

interface MCPTool {
  name: string;
  description: string;
  inputSchema: JSONSchema;
}

interface MCPToolResult {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    text?: string;
    data?: string;
    uri?: string;
  }>;
  isError?: boolean;
}

Python桥接API

Python桥接提供了直接访问CUDA Quantum：

class PythonBridge {
  // 内核管理
  createKernel(name: string, numQubits: number): Promise<PythonResponse>;
  applyGate(kernel: string, gate: string, qubits: number[]): Promise<PythonResponse>;

  // 执行
  sample(kernel: string, shots?: number): Promise<PythonResponse>;
  observe(kernel: string, hamiltonian: any[]): Promise<PythonResponse>;
  getState(kernel: string): Promise<PythonResponse>;

  // 配置
  setTarget(target: string, config?: any): Promise<PythonResponse>;
}

🚀 部署

Docker部署

FROM nvidia/cuda:11.8-runtime-ubuntu22.04

# 安装Node.js和Python
RUN apt-get update && apt-get install -y \\
    nodejs npm python3 python3-pip

# 安装CUDA Quantum
RUN pip3 install cudaq

# 复制并构建应用程序
COPY . /app
WORKDIR /app
RUN npm install && npm run build

# 启动服务器
CMD ["npm", "start"]

生产配置

# 生产环境
NODE_ENV=production
MCP_SERVER_NAME=cuda-quantum-mcp-prod
CUDAQ_DEFAULT_TARGET=qpp-gpu
LOG_LEVEL=info

# GPU优化
CUDA_VISIBLE_DEVICES=0,1,2,3
NVIDIA_VISIBLE_DEVICES=all

🤝 贡献

分叉仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m '添加神奇的功能'
推送到分支：git push origin feature/amazing-feature
打开拉取请求

开发设置

# 安装开发依赖
npm install

# 在开发模式下运行
npm run dev

# 运行代码检查
npm run lint

# 格式化代码
npm run format

📄 许可证

本项目根据MIT许可证发布 - 查看LICENSE文件了解详情。

🙏 致谢

NVIDIA CUDA Quantum团队，为优秀的量子计算框架
Anthropic，为模型上下文协议规范
量子计算社区，为灵感和反馈

📞 支持

文档：完整API文档
**问题