Files

Signed-off-by: ale <ale@manalejandro.com>

2025-10-08 02:57:03 +02:00

12 KiB

Original Blame Histórico

CUDA Quantum MCP Server - API Reference

Complete API documentation for the CUDA Quantum Model Context Protocol server.

Overview
Quantum Circuit Tools
Quantum Execution Tools
Hardware Backend Tools
Error Handling
Examples

Overview

The CUDA Quantum MCP Server provides quantum computing capabilities through standardized MCP tools. Each tool accepts JSON input and returns structured results.

Tool Response Format

All tools return responses in the MCP standard format:

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

Quantum Circuit Tools

create_quantum_kernel

Create a new quantum kernel (circuit) with specified qubits and parameters.

Input Schema:

{
  "name": "string (required)",
  "num_qubits": "integer 1-32 (required)", 
  "parameters": "array (optional)",
  "description": "string (optional)"
}

Parameters Array Schema:

{
  "name": "string",
  "type": "int|float|complex|list[int]|list[float]|list[complex]",
  "default": "any (optional)"
}

Example:

{
  "name": "my_circuit",
  "num_qubits": 4,
  "parameters": [
    {"name": "theta", "type": "float", "default": 0.0},
    {"name": "angles", "type": "list[float]"}
  ],
  "description": "My quantum circuit"
}

Response:

Successfully created quantum kernel 'my_circuit' with 4 qubits.

apply_quantum_gate

Apply a quantum gate to specified qubits in a quantum kernel.

Input Schema:

{
  "kernel_name": "string (required)",
  "gate_name": "string (required)",
  "qubits": "array[integer] (required)",
  "parameters": "array[number] (optional)",
  "controls": "array[integer] (optional)",
  "adjoint": "boolean (optional, default: false)"
}

Supported Gates:

Single-qubit: h, x, y, z, s, t
Parameterized: rx, ry, rz (require parameters)
Two-qubit: cx, cy, cz, swap
Multi-qubit: ccx, cswap

Example:

{
  "kernel_name": "my_circuit",
  "gate_name": "rx",
  "qubits": [0],
  "parameters": [1.5708],
  "adjoint": false
}

Controlled Gate Example:

{
  "kernel_name": "my_circuit",
  "gate_name": "x",
  "qubits": [1],
  "controls": [0]
}

Response:

Successfully applied rx gate to qubits [0] in kernel 'my_circuit'.

create_common_circuit

Create commonly used quantum circuits with predefined structures.

Input Schema:

{
  "circuit_type": "bell_pair|ghz_state|quantum_fourier_transform|grover_oracle|hadamard_test",
  "name": "string (required)",
  "num_qubits": "integer (optional, depends on circuit)",
  "parameters": "object (optional)"
}

Circuit Types:

bell_pair: Creates |00⟩ + |11⟩ state (2 qubits)
ghz_state: Creates |000...⟩ + |111...⟩ state (n qubits)
quantum_fourier_transform: QFT implementation
grover_oracle: Grover's oracle template
hadamard_test: Hadamard test circuit

Example:

{
  "circuit_type": "ghz_state",
  "name": "ghz_4",
  "num_qubits": 4
}

Response:

Successfully created ghz_state circuit named 'ghz_4' with 4 qubits.

list_quantum_kernels

List all available quantum kernels and their metadata.

Input Schema:

{
  "detailed": "boolean (optional, default: false)"
}

Example:

{
  "detailed": true
}

Response:

Available quantum kernels (2):

• my_circuit
  - Qubits: 4
  - Parameters: 2
  - Operations: 3

• ghz_4
  - Qubits: 4
  - Parameters: 0
  - Operations: 4

visualize_circuit

Generate a text-based visualization of a quantum circuit.

Input Schema:

{
  "kernel_name": "string (required)",
  "format": "text|qasm|json (optional, default: text)"
}

Example:

{
  "kernel_name": "my_circuit",
  "format": "text"
}

Response:

Quantum Circuit: my_circuit
Qubits: 4

Operations:
1. RX(1.5708) → qubits[0]
2. H → qubits[1]
3. X → qubits[2] (ctrl: 0)
4. CNOT → qubits[1,3]

Quantum Execution Tools

sample_quantum_circuit

Execute quantum circuit and sample measurement results.

Input Schema:

{
  "kernel_name": "string (required)",
  "shots": "integer 1-100000 (optional, default: 1000)",
  "parameters": "object (optional)",
  "target": "string (optional)"
}

Example:

{
  "kernel_name": "bell_pair",
  "shots": 5000,
  "parameters": {"theta": 1.57},
  "target": "qpp-gpu"
}

Response:

Sampling Results for 'bell_pair':

Shots: 5000
Results:
  |00⟩: 2487 (49.74%)
  |11⟩: 2513 (50.26%)

Entropy: 0.999 bits

observe_hamiltonian

Compute the expectation value of a Hamiltonian using a quantum circuit.

Input Schema:

{
  "kernel_name": "string (required)",
  "hamiltonian_terms": "array (required)",
  "shots": "integer (optional, default: 1000)",
  "parameters": "object (optional)"
}

Hamiltonian Terms Schema:

{
  "paulis": "array of ['I','X','Y','Z']",
  "qubits": "array[integer]",
  "coefficient": {
    "real": "number",
    "imag": "number"
  }
}

Example:

{
  "kernel_name": "my_ansatz",
  "hamiltonian_terms": [
    {
      "paulis": ["Z", "Z"],
      "qubits": [0, 1],
      "coefficient": {"real": 1.0, "imag": 0.0}
    },
    {
      "paulis": ["X", "X"],
      "qubits": [0, 1],
      "coefficient": {"real": 0.5, "imag": 0.0}
    }
  ],
  "shots": 10000
}

Response:

Hamiltonian Expectation Value for 'my_ansatz':

Expectation Value: -0.234567
Variance: 0.012345
Standard Deviation: 0.111111
Shots: 10000

Hamiltonian Terms:
  Term 1: 1.0 × (Z_0 ⊗ Z_1)
  Term 2: 0.5 × (X_0 ⊗ X_1)

get_quantum_state

Retrieve the quantum state vector from a quantum circuit.

Input Schema:

{
  "kernel_name": "string (required)",
  "parameters": "object (optional)",
  "format": "amplitudes|probabilities|both (optional, default: amplitudes)"
}

Example:

{
  "kernel_name": "bell_pair",
  "format": "both"
}

Response:

Quantum State for 'bell_pair':

State Vector Dimension: 4

Probability Amplitudes:
  |00⟩: 50.0000%
  |11⟩: 50.0000%

Complex Amplitudes:
  |00⟩: 0.707107 + 0.000000i
  |11⟩: 0.707107 + 0.000000i

State Properties:
  Purity: 1.000000
  Entanglement: Entangled

run_quantum_algorithm

Execute quantum algorithms with custom return values.

Input Schema:

{
  "kernel_name": "string (required)",
  "shots": "integer (optional, default: 1000)",
  "parameters": "object (optional)"
}

Example:

{
  "kernel_name": "grover_algorithm",
  "shots": 1000,
  "parameters": {"target_state": "101"}
}

variational_optimization

Perform variational quantum optimization using gradient-based methods.

Input Schema:

{
  "kernel_name": "string (required)",
  "hamiltonian_terms": "array (required)",
  "initial_parameters": "array[number] (required)",
  "optimizer": "cobyla|l-bfgs-b|gradient-descent (optional, default: cobyla)",
  "max_iterations": "integer 1-1000 (optional, default: 100)"
}

Example:

{
  "kernel_name": "vqe_ansatz",
  "hamiltonian_terms": [/* Hamiltonian definition */],
  "initial_parameters": [0.1, 0.2, 0.3],
  "optimizer": "cobyla",
  "max_iterations": 50
}

Hardware Backend Tools

set_quantum_target

Configure quantum execution target (simulator or hardware backend).

Input Schema:

{
  "target": "string (required)",
  "configuration": "object (optional)"
}

Available Targets:

Simulators: qpp-cpu, qpp-gpu, density-matrix-cpu, tensor-network
Hardware: ionq, quantinuum, quantum_machines, infleqtion, iqm, oqc, pasqal

Configuration Options:

{
  "shots": "integer",
  "optimization_level": "integer 0-3",
  "api_key": "string",
  "url": "string",
  "device": "string",
  "noise_model": "string",
  "error_mitigation": "boolean"
}

Example:

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

Response:

Successfully set quantum target to: qpp-gpu

Description: GPU State Vector Simulator (cuQuantum)

Configuration:
  shots: 10000
  optimization_level: 2

list_quantum_backends

List all available quantum backends and their capabilities.

Input Schema:

{
  "category": "all|simulators|hardware (optional, default: all)",
  "detailed": "boolean (optional, default: false)"
}

Example:

{
  "category": "simulators",
  "detailed": true
}

Response:

Available Quantum Backends:

🖥️  Simulators:
  • qpp-cpu: CPU State Vector Simulator
    - Local execution
    - GPU support: No
    - Max qubits: 32

  • qpp-gpu: GPU State Vector Simulator (cuQuantum)
    - Local execution
    - GPU support: Yes
    - Max qubits: 32

🔬 Hardware Providers:
  • ionq: IonQ Quantum Processors
    - Remote execution
    - Authentication required

get_platform_info

Get information about the current quantum platform and available resources.

Example:

{}

Response:

Quantum Platform Information:

Platform Name: default
Number of QPUs: 1
Is Simulator: true
Is Remote: false

System Information:
Node.js Version: v18.17.0
Platform: linux
Architecture: x64
CUDA Visible Devices: 0

test_backend_connectivity

Test connectivity to quantum hardware providers.

Input Schema:

{
  "backend": "string (required)",
  "credentials": "object (optional)"
}

Credentials Schema:

{
  "api_key": "string",
  "url": "string", 
  "username": "string",
  "password": "string"
}

Example:

{
  "backend": "qpp-gpu",
  "credentials": {}
}

Response:

Testing connectivity to qpp-gpu...

✅ qpp-gpu is available (local simulator)
✅ CUDA device available: 0

configure_gpu_acceleration

Configure GPU acceleration for quantum simulations.

Input Schema:

{
  "enable": "boolean (required)",
  "device_id": "integer (optional)",
  "memory_limit": "number (optional)",
  "target": "qpp-gpu|density-matrix-gpu (optional, default: qpp-gpu)"
}

Example:

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

Response:

GPU Acceleration Configuration:

✅ Enabling GPU acceleration
Target: qpp-gpu
GPU Device ID: 0
Memory Limit: 8.0 GB
✅ Successfully configured GPU target

Note: Ensure NVIDIA drivers and CUDA toolkit are installed.

Error Handling

All tools return standardized error responses when failures occur:

{
  "content": [
    {
      "type": "text",
      "text": "Error message describing what went wrong"
    }
  ],
  "isError": true
}

Common Error Types

Validation Errors: Invalid input parameters
Python Bridge Errors: CUDA Quantum not available or timeout
Execution Errors: Quantum circuit execution failures
Backend Errors: Hardware provider connectivity issues

Error Recovery

Timeout Errors: Increase timeout in configuration
GPU Errors: Check CUDA installation and device availability
API Errors: Verify credentials and network connectivity
Memory Errors: Reduce circuit size or enable GPU

Examples

Complete Quantum Algorithm Example

// 1. Create parameterized ansatz
{
  "tool": "create_quantum_kernel",
  "input": {
    "name": "vqe_h2",
    "num_qubits": 4,
    "parameters": [
      {"name": "theta1", "type": "float"},
      {"name": "theta2", "type": "float"}
    ]
  }
}

// 2. Build ansatz circuit
{
  "tool": "apply_quantum_gate", 
  "input": {
    "kernel_name": "vqe_h2",
    "gate_name": "ry",
    "qubits": [0],
    "parameters": ["theta1"]
  }
}

// 3. Set GPU target
{
  "tool": "set_quantum_target",
  "input": {
    "target": "qpp-gpu"
  }
}

// 4. Compute expectation value
{
  "tool": "observe_hamiltonian",
  "input": {
    "kernel_name": "vqe_h2",
    "hamiltonian_terms": [
      {
        "paulis": ["Z", "Z", "I", "I"],
        "qubits": [0, 1, 2, 3],
        "coefficient": {"real": -1.0523732, "imag": 0.0}
      }
    ],
    "parameters": {"theta1": 0.5, "theta2": 1.2}
  }
}

This API reference provides comprehensive documentation for all available tools and their usage patterns in the CUDA Quantum MCP Server.

12 KiB Original Blame Histórico No Escapar Escapar

CUDA Quantum MCP Server - API Reference

Table of Contents

Overview

Tool Response Format

Quantum Circuit Tools

create_quantum_kernel

apply_quantum_gate

create_common_circuit

list_quantum_kernels

visualize_circuit

Quantum Execution Tools

sample_quantum_circuit

observe_hamiltonian

get_quantum_state

run_quantum_algorithm

variational_optimization

Hardware Backend Tools

set_quantum_target

list_quantum_backends

get_platform_info

test_backend_connectivity

configure_gpu_acceleration

Error Handling

Common Error Types

Error Recovery

Examples

Complete Quantum Algorithm Example

12 KiB

Original Blame Histórico