QPanda3 Runtime MCP Server

Configure Origin Quantum qcloud account authentication.

Set up credentials to access Origin Quantum computing services. You can provide credentials directly, via a config file, or through environment variables.

Args: api_key: API key for authentication. If not provided, reads from QPANDA3_API_KEY environment variable. channel: Channel type - always "qcloud". config_path: Path to config.yml file containing api_key.

Returns: Setup status and account information including: - status: "success" or "error" - message: Status description - channel: The channel being used - available_devices: Number of accessible QPU devices

Example: # Using direct credentials setup_origin_quantum_account_tool(api_key="your_api_key")

# Using config file
setup_origin_quantum_account_tool(config_path="./config.yml")

List saved account information.

Returns information about the current session's authentication status. QPanda3 Runtime uses session-based authentication rather than persistent account storage.

Returns: Dictionary containing: - status: "success" or "error" - accounts: List of account information - message: Status description

Get information about the currently active account.

Returns details about the account being used in the current session, including channel type and connection status.

Returns: Dictionary containing: - status: "success" or "error" - account: Account details including channel and connection status

List all available QPU (Quantum Processing Unit) devices.

Retrieves a list of all quantum computing devices accessible through the current account.

Returns: Dictionary containing: - status: "success" or "error" - devices: List of devices, each with: - id: Device identifier - name: Device name - num_qubits: Number of qubits - operational: Whether device is operational - total_devices: Total count of available devices

Example: devices = list_qpu_devices_tool() # Use devices["devices"][0]["id"] to get device ID for other tools

Get detailed properties of a specific QPU device.

Retrieve comprehensive information about a quantum computing device including its capabilities and current status.

Args: device_id: The ID of the quantum device (e.g., '20'). Use list_qpu_devices_tool to find available device IDs.

Returns: Dictionary containing: - status: "success" or "error" - device_id: The requested device ID - num_qubits: Number of qubits on the device - topology: Qubit connectivity information - basis_gates: Native gates supported by the device - operational: Current operational status

Example: props = get_qpu_properties_tool("20") print(f"Device has {props['num_qubits']} qubits")

Execute quantum circuit sampling task.

Submit a quantum circuit for sampling on a QPU device. Sampling executes the circuit multiple times and returns the measurement outcome distribution.

Args: circuit: Quantum circuit(s) to execute. Accepts: - Single circuit as string (QProg/QCircuit/OriginIR format) - List of circuits for batch execution - OriginIR example: QINIT 2 CREG 2 H q[0] CNOT q[0],q[1] MEASURE q[0],c[0] MEASURE q[1],c[1] device_id: Target device ID (e.g., '20'). Use list_qpu_devices_tool to find available devices. shots: Number of sampling shots (default: 1000). Higher values give more statistical accuracy. measure_qubits: Qubit indices to measure (optional). If not specified, uses measurement operations in the circuit.

Returns: Dictionary containing: - status: "success" or "error" - task_id: ID for tracking the task - device_id: Target device - shots: Number of shots requested - message: Status message - note: Instructions for retrieving results

Example: # Submit a Bell state circuit for sampling result = sample_tool( circuit="QINIT 2\nCREG 2\nH q[0]\nCNOT q[0],q[1]\nMEASURE q[0],c[0]\nMEASURE q[1],c[1]", device_id="20", shots=1000 ) task_id = result["task_id"]

Note: Use get_task_status_tool to check progress and get_task_results_tool to retrieve results after the task completes.

Execute expectation estimation task.

Submit a quantum circuit for expectation value estimation. This computes the expectation value ⟨ψ|O|ψ⟩ where |ψ⟩ is the quantum state produced by the circuit and O is the observable.

Args: circuit: Quantum circuit(s) to execute. Accepts: - Single circuit as string (QProg/QCircuit/OriginIR format) - List of circuits for batch execution - Note: Circuit should NOT contain measurement operations observable: Observable to measure. Accepts: - Dict format: {"Z0 Z1": 0.5, "X0": -0.3} - Pauli operator string: "IIXY" device_id: Target device ID (e.g., '20').

Returns: Dictionary containing: - status: "success" or "error" - task_id: ID for tracking the task - device_id: Target device - message: Status message - note: Instructions for retrieving results

Example: # Estimate expectation value of Z0*Z1 result = estimate_tool( circuit="QINIT 2\nCREG 2\nH q[0]\nCNOT q[0],q[1]", observable="Z0 Z1", device_id="20" )

Note: Use get_task_status_tool to check progress and get_task_results_tool to retrieve results after the task completes.

Get the execution status of a task.

Check the current status of a submitted quantum computing task.

Args: task_id: The ID of the task (returned by sample_tool or estimate_tool).

Returns: Dictionary containing: - status: "success" or "error" - task_id: The task ID - task_status: One of: - "PENDING": Waiting to execute - "RUNNING": Currently executing - "DONE": Completed successfully - "FAILED": Execution failed - "CANCELLED": Cancelled by user - progress: Execution progress (if available) - error_message: Error description (if failed)

Example: status = get_task_status_tool("task_12345") if status["task_status"] == "DONE": results = get_task_results_tool("task_12345")

Get the computation results of a completed task.

Retrieve the results from a completed quantum computing task. The task must be in DONE status to retrieve results.

Args: task_id: The ID of the completed task.

Returns: For sampling tasks: - status: "success", "pending", or "error" - task_id: The task ID - task_status: Current status - results: List of measurement outcomes, each containing: - key: List of measurement outcomes (hex format, e.g., "0x0", "0x3") - value: Corresponding probabilities or counts - message: Status message

For estimation tasks:
- status: "success", "pending", or "error"
- task_id: The task ID
- task_status: Current status
- results: Expectation value(s)
- message: Status message

Example: # First check status status = get_task_status_tool("task_12345") if status["task_status"] == "DONE": # Then get results results = get_task_results_tool("task_12345") print(f"Measurement outcomes: {results['results']}")

Cancel a running or pending task.

Request cancellation of a submitted task. This is only effective if the task has not yet completed.

Args: task_id: The ID of the task to cancel.

Returns: Dictionary containing: - status: "success" or "error" - task_id: The task ID - message: Cancellation status

Example: cancel_task_tool("task_12345")

List user's recent tasks.

Retrieve a list of recently submitted quantum computing tasks.

Args: limit: Maximum number of tasks to return (default: 10).

Returns: Dictionary containing: - status: "success" or "error" - tasks: List of task information, each containing: - task_id: Task identifier - status: Current task status - creation_date: When task was created - backend: Target device - total_tasks: Total number of tasks returned

Example: tasks = list_my_tasks_tool(limit=5) for task in tasks["tasks"]: print(f"{task['task_id']}: {task['status']}")

Create a CircuitObservableBinding for multi-objective quantum decision making.

This creates a program set that manages multiple quantum circuits and multiple observables for multi-target decision paradigms. This is useful for quantum multi-objective decision scenarios where you need to evaluate multiple strategies (circuits) against multiple objective dimensions (observables).

Args: circuits: List of quantum circuits in QProg/QCircuit/OriginIR format. Each circuit represents a different strategy to evaluate. observables: List of observables (Hamiltonians). Each observable represents a different objective dimension to measure. Supports dict format: {"Z0 Z1": 0.5, "X0": -0.3}

Returns: Dictionary containing: - status: "success" or "error" - binding_id: Unique ID for referencing this binding (use with add_product_rule_tool, add_zip_rule_tool, and estimate_with_binding_tool) - num_circuits: Number of circuits in the binding - num_observables: Number of observables in the binding - message: Status description

Example: # Create binding with 3 circuits and 2 observables binding = create_circuit_observable_binding_tool( circuits=[ "QINIT 2\nCREG 2\nH q[0]\nCNOT q[0],q[1]", "QINIT 2\nCREG 2\nX q[0]\nCNOT q[0],q[1]", "QINIT 2\nCREG 2\nZ q[0]\nSWAP q[0],q[1]" ], observables=[ {"Z0 Z1": 1.0}, {"X0": 0.5} ] ) binding_id = binding["binding_id"]

Note: After creating a binding, use add_product_rule_tool or add_zip_rule_tool to define the combinations, then use estimate_with_binding_tool to submit.

Add product (Cartesian product) rule to CircuitObservableBinding.

This generates all combinations of the specified circuits with the specified observables. This is analogous to Python's itertools.product function.

For example, if circuit_indices=[0,1,2] and observable_indices=[0,1], it generates combinations: (0,0), (0,1), (1,0), (1,1), (2,0), (2,1).

Args: binding_id: The ID returned by create_circuit_observable_binding_tool. circuit_indices: List of circuit indices to include in the product. observable_indices: List of observable indices to include in the product.

Returns: Dictionary containing: - status: "success" or "error" - binding_id: The binding ID - combinations_added: Number of combinations added - message: Status description

Example: # Add all combinations of 3 circuits with 2 observables (6 total) result = add_product_rule_tool( binding_id="your_binding_id", circuit_indices=[0, 1, 2], observable_indices=[0, 1] ) # This adds combinations: (0,0), (0,1), (1,0), (1,1), (2,0), (2,1)

Add zip (one-to-one) rule to CircuitObservableBinding.

This generates one-to-one pairs of circuits and observables. This is analogous to Python's zip function.

For example, if circuit_indices=[0,2] and observable_indices=[1,0], it generates combinations: (0,1), (2,0).

Args: binding_id: The ID returned by create_circuit_observable_binding_tool. circuit_indices: List of circuit indices (must match length of observable_indices). observable_indices: List of observable indices (must match length of circuit_indices).

Returns: Dictionary containing: - status: "success" or "error" - binding_id: The binding ID - combinations_added: Number of combinations added - message: Status description

Example: # Add specific circuit-observable pairs result = add_zip_rule_tool( binding_id="your_binding_id", circuit_indices=[0, 2], observable_indices=[1, 0] ) # This adds 2 combinations: (circuit_0, observable_1), (circuit_2, observable_0)

Execute expectation estimation using CircuitObservableBinding.

Submit a multi-objective expectation estimation task using the previously created CircuitObservableBinding with its product/zip rules defined.

Args: binding_id: The ID returned by create_circuit_observable_binding_tool. device_id: Target device ID (e.g., '20').

Returns: Dictionary containing: - status: "success" or "error" - task_id: ID for tracking the task - binding_id: The binding ID used - device_id: Target device - message: Status message - note: Instructions for retrieving results

Example: # After creating binding and adding rules result = estimate_with_binding_tool( binding_id="your_binding_id", device_id="20" ) task_id = result["task_id"]

Note: Use get_task_status_tool and get_task_results_tool to check progress and retrieve results.

List all stored CircuitObservableBinding objects.

Returns a list of all bindings created in the current session.

Returns: Dictionary containing: - status: "success" or "error" - bindings: List of binding information - total_bindings: Total count of bindings

Delete a stored CircuitObservableBinding object.

Remove a binding from the session storage.

Args: binding_id: The ID of the binding to delete.

Returns: Dictionary containing: - status: "success" or "error" - message: Status description

Execute batch quantum circuit sampling task.

Submit multiple quantum circuits for sampling in a single batch. This is more efficient than submitting circuits one by one.

Args: circuits: List of quantum circuits in QProg/QCircuit/OriginIR format. device_id: Target device ID (e.g., '20'). shots: Number of sampling shots per circuit (default: 1000). measure_qubits: Qubit indices to measure (optional). If not specified, uses measurement operations in the circuits.

Returns: Dictionary containing: - status: "success" or "error" - task_id: ID for tracking the task - device_id: Target device - num_circuits: Number of circuits in the batch - shots: Number of shots per circuit - message: Status message

Example: result = batch_sample_tool( circuits=[ "QINIT 2\nCREG 2\nH q[0]\nCNOT q[0],q[1]\nMEASURE q[0],c[0]\nMEASURE q[1],c[1]", "QINIT 2\nCREG 2\nX q[0]\nCNOT q[0],q[1]\nMEASURE q[0],c[0]\nMEASURE q[1],c[1]" ], device_id="20", shots=1000 )

Note: Use get_task_status_tool and get_task_results_tool to check progress and retrieve results.

Execute batch expectation estimation with a single observable.

Submit multiple quantum circuits for expectation value estimation with a single observable. This is the "n circuits + 1 observable" pattern, useful for comparing different circuit strategies against the same metric.

Args: circuits: List of quantum circuits in QProg/QCircuit/OriginIR format. Note: Circuits should NOT contain measurement operations. observable: Observable to measure for all circuits. Supports: - Dict format: {"Z0 Z1": 0.5, "X0": -0.3} device_id: Target device ID (e.g., '20').

Returns: Dictionary containing: - status: "success" or "error" - task_id: ID for tracking the task - device_id: Target device - num_circuits: Number of circuits in the batch - message: Status message

Example: result = batch_estimate_tool( circuits=[ "QINIT 2\nCREG 2\nH q[0]\nCNOT q[0],q[1]", "QINIT 2\nCREG 2\nX q[0]\nCNOT q[0],q[1]" ], observable={"Z0 Z1": 1.0}, device_id="20" )

Note: Use get_task_status_tool and get_task_results_tool to check progress and retrieve results.