713
API.md
Archivo normal
713
API.md
Archivo normal
@@ -0,0 +1,713 @@
|
||||
# CUDA Quantum MCP Server - API Reference
|
||||
|
||||
Complete API documentation for the CUDA Quantum Model Context Protocol server.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Quantum Circuit Tools](#quantum-circuit-tools)
|
||||
- [Quantum Execution Tools](#quantum-execution-tools)
|
||||
- [Hardware Backend Tools](#hardware-backend-tools)
|
||||
- [Error Handling](#error-handling)
|
||||
- [Examples](#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:
|
||||
|
||||
```typescript
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"name": "string (required)",
|
||||
"num_qubits": "integer 1-32 (required)",
|
||||
"parameters": "array (optional)",
|
||||
"description": "string (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
**Parameters Array Schema:**
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"type": "int|float|complex|list[int]|list[float]|list[complex]",
|
||||
"default": "any (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "my_circuit",
|
||||
"gate_name": "rx",
|
||||
"qubits": [0],
|
||||
"parameters": [1.5708],
|
||||
"adjoint": false
|
||||
}
|
||||
```
|
||||
|
||||
**Controlled Gate Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"detailed": "boolean (optional, default: false)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "string (required)",
|
||||
"format": "text|qasm|json (optional, default: text)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "string (required)",
|
||||
"shots": "integer 1-100000 (optional, default: 1000)",
|
||||
"parameters": "object (optional)",
|
||||
"target": "string (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "string (required)",
|
||||
"hamiltonian_terms": "array (required)",
|
||||
"shots": "integer (optional, default: 1000)",
|
||||
"parameters": "object (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
**Hamiltonian Terms Schema:**
|
||||
```json
|
||||
{
|
||||
"paulis": "array of ['I','X','Y','Z']",
|
||||
"qubits": "array[integer]",
|
||||
"coefficient": {
|
||||
"real": "number",
|
||||
"imag": "number"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "string (required)",
|
||||
"parameters": "object (optional)",
|
||||
"format": "amplitudes|probabilities|both (optional, default: amplitudes)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "string (required)",
|
||||
"shots": "integer (optional, default: 1000)",
|
||||
"parameters": "object (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"kernel_name": "grover_algorithm",
|
||||
"shots": 1000,
|
||||
"parameters": {"target_state": "101"}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### variational_optimization
|
||||
|
||||
Perform variational quantum optimization using gradient-based methods.
|
||||
|
||||
**Input Schema:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"shots": "integer",
|
||||
"optimization_level": "integer 0-3",
|
||||
"api_key": "string",
|
||||
"url": "string",
|
||||
"device": "string",
|
||||
"noise_model": "string",
|
||||
"error_mitigation": "boolean"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"category": "all|simulators|hardware (optional, default: all)",
|
||||
"detailed": "boolean (optional, default: false)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
**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:**
|
||||
```json
|
||||
{
|
||||
"backend": "string (required)",
|
||||
"credentials": "object (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
**Credentials Schema:**
|
||||
```json
|
||||
{
|
||||
"api_key": "string",
|
||||
"url": "string",
|
||||
"username": "string",
|
||||
"password": "string"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"enable": "boolean (required)",
|
||||
"device_id": "integer (optional)",
|
||||
"memory_limit": "number (optional)",
|
||||
"target": "qpp-gpu|density-matrix-gpu (optional, default: qpp-gpu)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Error message describing what went wrong"
|
||||
}
|
||||
],
|
||||
"isError": true
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Types
|
||||
|
||||
1. **Validation Errors**: Invalid input parameters
|
||||
2. **Python Bridge Errors**: CUDA Quantum not available or timeout
|
||||
3. **Execution Errors**: Quantum circuit execution failures
|
||||
4. **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
|
||||
|
||||
```json
|
||||
// 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.
|
||||
Referencia en una nueva incidencia
Block a user