QPanda3 Runtime: A Runtime Toolkit for Real Quantum Computing

Breaking Cost Barriers: Making Quantum Development No Longer Luxurious

Currently, real quantum computing is moving from the laboratory to practical applications, but high development and execution costs remain a key bottleneck preventing widespread participation among researchers and developers. Under traditional development models, once there are compatibility issues in circuit design or improper parameter configurations, it can lead to wasted precious machine time on real devices, resulting in both time and economic losses. Additionally, real quantum device resources are scarce and queue wait times are long, making debugging and iteration processes inefficient. The lack of effective local validation methods further amplifies trial-and-error costs. For variational algorithms (such as VQE, QAOA) that rely on high-frequency parameter tuning, each remote call comes with significant latency and overhead, seriously affecting algorithm convergence efficiency and user experience.

To address these challenges, we introduce QPanda3 Runtime, an efficient runtime toolkit specifically designed for real quantum computing scenarios.

Breaking cost barriers starts now — quantum development should not be a privilege for a few, but a stage for all innovators.

What Is QPanda3 Runtime

QPanda3 Runtime is a toolkit for Origin Quantum's real quantum computing services, providing concise and efficient programming interfaces for submitting and managing quantum computing tasks (sampling tasks and expectation estimation tasks). Through encapsulation and optimization of the underlying quantum computing workflow, QPanda3 Runtime can significantly reduce quantum application development costs and execution overhead, allowing researchers and developers to focus more on the algorithms themselves rather than infrastructure details.

Quick Start

Installation

Execute the following command in the command line to install the qpanda3_runtime library. If you need to install an offline whl package, please replace qpanda3_runtime with the file path of the offline whl.

pip install qpanda3_runtime

Toolkit Features

Focused

QPanda3 Runtime focuses on two core areas in quantum computing: 1. It is dedicated to real quantum computers and quantum chips, committed to supporting program development and deployment in practical application scenarios; 2. It focuses on sampling and expectation estimation, two critical core quantum computing operations.

Efficient

QPanda3 Runtime provides a multi-objective decision paradigm, transforming classical multi-objective optimization problems into quantum-processable forms, efficiently supporting the modeling, evaluation, and optimization closed-loop for multi-objective problems. QPanda3 Runtime also provides iterative parameter tuning tasks, reducing latency and overhead during the iteration process.

Easy to Use

QPanda3 Runtime supports users in pre-validating whether quantum circuits can be compiled on specified chips before submitting tasks to real quantum devices, and can also use limited noise simulation to preliminarily evaluate whether quantum circuits meet expectations, avoiding waste of remote resources due to circuit errors or configuration issues. Additionally, QPanda3 Runtime supports flexible credential usage methods, simplifying the work of updating credentials in large-scale software systems.

Quantum Computing on QPU

Using QPanda3 Runtime for quantum computing on a QPU (Quantum Processing Unit) typically requires four steps:

Step 1: Obtain a Valid API Key for the Channel

• Users need to obtain an api_key from the Origin Quantum Cloud Management Platform
• Users need to contact Origin Quantum Cloud administrators to enable permissions for their existing api_key

Step 2: Login

• Use the information in config.yml to log in to the access channel for the computing backend

Step 3: Define and Submit Quantum Computing Tasks

• Supports sampling and expectation estimation two basic quantum computing task types
• Supports real quantum computers/chip devices as quantum computing equipment
• Supports general sessions or sessions for variational quantum computing to meet scenarios requiring continuous execution of user computing tasks

Step 4: Query Computing Task Execution Results

• QPanda3 Runtime supports one blocking plus three non-blocking methods for querying computing task execution results/status, to flexibly adapt to various development scenarios.
• QPanda3 Runtime's methods for querying task results balance flexibility and practicality. All methods return results in a unified format and are compatible with both sampling and expectation estimation tasks. Developers can flexibly choose based on program structure and response requirements.

A Simple Example

Define and submit an expectation estimation task:

from qpanda3_runtime import RuntimeService
from pyqpanda3.core import *
from pyqpanda3.hamiltonian import Hamiltonian

# Use data from config.yml configuration file to log in
# Logging in occurs when the RuntimeService object is generated
service = RuntimeService()
service.login('your_valid_api_key')
# Design/define quantum circuit
prog = QProg()
prog << X(0)<<CNOT(0,1)

ham = Hamiltonian([('XZ', [0, 1], 3.14),('XZ', [0, 1], 1.14), ('ZY', [0, 1], 5.14)])

# Use RuntimeService.estimate to generate a local management object task for the computing task
task = service.estimate(
    circuit_with_observable=(prog,ham),
    # For QPU, need to use RuntimeService.device interface to return device object, parameter is QPU id
    device=service.device('WK_C180'),
)
# Query computing task execution result
res = task.get_result_sync()
print(f'res:{res}')

Built-In Utility Tools

QPanda3 Runtime provides a series of utility tools to enhance user experience, such as: supporting tracking and state saving of task execution processes through Tracker and CheckPoint features, facilitating debugging and recovery of long-running computing tasks.

Tracker

Tracker is a toolkit for tracking and analyzing quantum program execution processes. It helps you record the execution status of quantum computing tasks, including execution time, parameter changes, result data and other information, allowing you to better understand and optimize quantum programs.

Three Usage Modes

Tracker has three usage modes: context manager, decorator, and manual tracking. These cover automatic tracking at the code block level, non-invasive automatic tracking at the function level, and manual mode covering custom scenarios that require fine-grained control over tracking timing.

Typical Application Scenarios

• Error debugging and task recovery
• Tracking iterative optimization of parameterized quantum circuits

A Simple Example

This example demonstrates the basic usage of Tracker:

1. Enable automatic tracking when initializing RuntimeService
2. Use the with statement to create a tracking context
3. Record data within the context

# Initialize RuntimeService
service = RuntimeService(auto_track=True, trace_record_file='./trace_record.jsonl')
service.login('your_valid_api_key')
# Use context manager for tracking
with Tracker(service, name="quantum_operation") as t:
    # Record data
    t.record({"operation": "quantum_circuit", "qubit_count": 2})
    # Quantum operations can be executed here
    # ...
    # Record results
    t.record({"result": "success"})

This example demonstrates the basic usage of Tracker:

1. Enable automatic tracking when initializing RuntimeService
2. Use the with statement to create a tracking context

CheckPoint

CheckPoint is a utility tool in qpanda3_runtime used to save and restore state during quantum computing tasks. Imagine playing a game where you can save your progress at any time — CheckPoint is the "save point" functionality in quantum computing.

Core Functionality

In quantum computing, many tasks require long running times, such as: iterative optimization of variational quantum algorithms (VQE, QAOA), sampling tasks for large-scale quantum circuits, and multiple attempts at complex quantum experiments. In these task scenarios, using CheckPoint can achieve the following:

• Prevent data loss: tasks can recover from checkpoints if unexpectedly interrupted
• Facilitate debugging: save intermediate states for problem analysis
• Optimize resources: tasks can be paused and resumed later
• Record progress: save task execution history

Typical Application Scenarios

• Use CheckPoint in variational quantum algorithms (such as VQE) to save the state of each iteration
• For long-running sampling tasks, use CheckPoint to save intermediate results
• Save complete experiment configuration and execution history

A Simple Example

This simple example demonstrates the two core functionalities of CheckPoint: saving and restoring data:

# Import necessary modules
from qpanda3_runtime import CheckPoint
# Create CheckPoint instance
checkpoint = CheckPoint()
# Save a checkpoint
task_state = {"task_id": "my_task", "status": "running", "progress": 0.5}
user_data = {"algorithm": "test", "iteration": 1}
saved_file = checkpoint.save(
    filepath="my_first_checkpoint.json",
    task_state=task_state,
    user_data=user_data
)
print(f"Checkpoint saved to: {saved_file}")
# Load checkpoint
loaded_data = checkpoint.load(saved_file)
print(f"Loaded task state: {loaded_data['task_state']}")
print(f"Loaded user data: {loaded_data['user_data']}")

Vision

With QPanda3 Runtime, developers no longer need to consume real machine resources for preliminary debugging, nor do they need to lose themselves in infrastructure details. Instead, they benefit from a concise and unified programming interface, efficient local simulation verification mechanisms, and native support for multi-objective decision and parameterized optimization tasks. We hope that through QPanda3 Runtime, every developer who aspires to explore the quantum future can easily, efficiently, and cost-effectively harness real quantum computing power.