Skip to content

getting_started.md

Latest commit

 

History

History
220 lines (163 loc) · 6.47 KB

getting_started.md

File metadata and controls

220 lines (163 loc) · 6.47 KB
Raw

Getting Started - Complete Beginner's Guide

Welcome to QPanda3 Runtime MCP Server! This guide will help you get started from scratch, even if you're new to quantum computing or MCP servers.

What is This?

QPanda3 Runtime MCP Server is a bridge that connects AI assistants (like Claude, ChatGPT, or custom AI agents) to Origin Quantum's quantum computing services. With this server, you can:

  • Ask an AI assistant to run quantum circuits on real quantum computers
  • Let AI manage your quantum computing tasks
  • Build AI-powered quantum computing applications

Setup

If you haven't installed the server yet, follow these guides first:

  1. Installation Guide - Install dependencies and configure your API key
  2. Configuration Guide - Connect to your AI coding platform (Claude, Cline, Cursor, etc.)

Your First Quantum Circuit

Once connected to an AI assistant, try these prompts:

Example 1: List Available Devices

List all available QPU devices

The AI will call list_qpu_devices_tool and show you available quantum computers.

Example 2: Run a Bell State Circuit

Run a Bell state circuit on device 20 with 1000 shots

The AI will:

  1. Use the Bell state circuit (creates quantum entanglement)
  2. Submit it to the specified device
  3. Return the measurement results

Expected results: ~50% 00 and ~50% 11 (quantum entanglement!)

Example 3: Check Task Status

Check the status of my last task

Understanding the Tools

Account Management

Tool What It Does When to Use
setup_origin_quantum_account_tool Configure your credentials First time setup
list_saved_accounts_tool List session accounts Check authentication
active_account_info_tool Get current account info Verify connection

Device Management

Tool What It Does When to Use
list_qpu_devices_tool List all quantum devices Find available QPUs
get_qpu_properties_tool Get device details Check device capabilities

Task Execution

Tool What It Does When to Use
sample_tool Run circuit with measurements Get measurement outcomes
estimate_tool Calculate expectation value Quantum chemistry, VQE
batch_sample_tool Run multiple circuits Compare circuits
batch_estimate_tool Estimate multiple circuits Optimization tasks

Task Management

Tool What It Does When to Use
get_task_status_tool Check if task is done Monitor progress
get_task_results_tool Get task results Retrieve output
cancel_task_tool Cancel a task Stop execution
list_my_tasks_tool List recent tasks Review history

Multi-Objective Decisions

Tool What It Does When to Use
create_circuit_observable_binding_tool Create binding Multi-objective optimization
add_product_rule_tool Add all combinations Test all pairs
add_zip_rule_tool Add specific pairs Custom combinations
estimate_with_binding_tool Execute binding Run estimation
list_bindings_tool List bindings Manage bindings
delete_binding_tool Delete binding Cleanup

Pre-Built Circuit Resources

The server provides ready-to-use quantum circuits:

Resource Description Qubits Expected Results
circuits://bell-state Quantum entanglement 2 50% 00, 50% 11
circuits://ghz-state Multi-qubit entanglement 3 50% 000, 50% 111
circuits://random Random number generator 4 Equal distribution
circuits://superposition Single qubit demo 1 50% 0, 50% 1

Writing Your Own Circuits

Circuits use the OriginIR format:

QINIT <number_of_qubits>
CREG <number_of_classical_bits>
<gate_operations>
MEASURE q[i],c[i]

Common Gates

Gate Syntax Description
Hadamard H q[0] Superposition
Pauli-X X q[0] Bit flip
Pauli-Y Y q[0] Bit+Phase flip
Pauli-Z Z q[0] Phase flip
CNOT CNOT q[0],q[1] Controlled-NOT
CZ CZ q[0],q[1] Controlled-Z
Measure MEASURE q[0],c[0] Measure to classical bit

Example: Custom Circuit

# A 3-qubit GHZ-like circuit
circuit = """QINIT 3
CREG 3
H q[0]
CNOT q[0],q[1]
CNOT q[1],q[2]
MEASURE q[0],c[0]
MEASURE q[1],c[1]
MEASURE q[2],c[2]"""

Understanding Observables

For estimation tasks, you need to define observables (what to measure):

Dictionary Format

observable = {
    "Z0 Z1": 1.0,   # Measure Z on qubits 0 and 1
    "X0": 0.5       # Measure X on qubit 0
}

Pauli String Format

observable = "IIXY"  # 4-qubit observable

Task Workflow

graph LR
    A[Submit Task] --> B[Check Status]
    B --> C{Status?}
    C -->|PENDING| B
    C -->|RUNNING| B
    C -->|DONE| D[Get Results]
    C -->|FAILED| E[Handle Error]
Loading

Complete Example

# 1. Submit task
result = await sample_tool(
    circuit=bell_state_circuit,
    device_id="20",
    shots=1000
)
task_id = result["task_id"]

# 2. Poll for completion
import asyncio
while True:
    status = await get_task_status_tool(task_id)
    if status["task_status"] == "DONE":
        break
    elif status["task_status"] == "FAILED":
        raise Exception("Task failed!")
    await asyncio.sleep(2)

# 3. Get results
results = await get_task_results_tool(task_id)
print(f"Results: {results['results']}")

Security Tips

  1. Never commit .env files - Add to .gitignore
  2. Use environment variables for credentials in production
  3. Restrict file permissions: chmod 600 .env

Next Steps

Getting Help