0.5.1

pyqpanda3 v0.5.1 (2026-10-27) is a maintenance and cloud-service enhancement release on top of 0.5.0. The themes are QCloud access and correction configuration, the result semantics of failed jobs, random circuits that follow the chip topology, and an initial-state interface for the GPU simulator; the release also includes stability and regression-test improvements that do not change the Python API.

1. QCloud service resolution from the API key

QCloudService(api_key) gains a single-argument constructor: a new-format API key carries its service domain, which pyqpanda3 resolves to connect to the corresponding service. Legacy API keys do not carry a domain and fall back to the historical default cloud endpoint.

QCloudService(api_key, url) remains available; url explicitly overrides the domain encoded in the API key and is intended for testing or private deployments. In the 0.5.1 bindings url no longer has a default value: pass it explicitly when you need a custom address.

from pyqpanda3.qcloud import QCloudService

# New-format key: the service domain is resolved from the key
service = QCloudService(api_key="YOUR_API_KEY")

# Explicit URL: overrides the domain encoded in the key (testing or private deployments)
service = QCloudService(
    api_key="YOUR_API_KEY",
    url="https://custom-cloud.example.com",
)

NOTE

The examples above require cloud credentials and a real task; they cannot run locally.

2. Configurable correction modes and crosstalk suppression

QCloudOptions(...) now supports keyword construction, with defaults: amend_flag=1, use_cz_pattern=False, mapping=True, optimization=True, point_label=1, is_prob_counts=True, specified_block=[].

amend_flag selects the result-correction mode: 0 disables correction, 1 enables global sampling correction, and 3 enables local real-time correction. use_cz_pattern controls crosstalk noise suppression.

Added set_amend_flag / amend_flag and set_use_cz_pattern / use_cz_pattern; the existing set_amend and the other setters are unchanged.

QCloudOptions.print() now prints is_prob_counts, amend_flag, use_cz_pattern, mapping, optimization, point_label (plus custom options), and no longer prints amend.

from pyqpanda3.qcloud import QCloudOptions

options = QCloudOptions(
    amend_flag=3,          # 0: off, 1: global sampling, 3: local real-time
    use_cz_pattern=True,   # enable crosstalk noise suppression
    mapping=True,
    optimization=True,
    point_label=1,
    is_prob_counts=True,
    specified_block=[],
)
options.print()

NOTE

The options object above can be built locally; submitting a job still requires cloud credentials and a real task, and cannot run locally.

3. Failed jobs no longer raise

QCloudJob.result() keeps polling only while the job status is WAITING / COMPUTING / QUEUING; FINISHED / FAILED return immediately.

A server-reported task failure no longer raises RuntimeError; result() returns a QCloudResult whose job_status() == JobStatus.FAILED, and error_message() gives the reason (preferring obj.errInfo, then message, then errCode). Transport-level errors such as network, protocol, or HTTP failures may still be raised by the underlying request.

from pyqpanda3.qcloud import JobStatus

# job = backend.run(...)
result = job.result()
if result.job_status() == JobStatus.FAILED:
    print("failed:", result.error_message())
else:
    print(result.get_probs())

NOTE

The example above requires cloud credentials and a real task; it cannot run locally.

4. Random circuits follow the chip topology

New topology-constrained random-circuit generation:

• random_qcircuit(qubits, depth, gate_type, topology)
• random_qprog(qubits, depth, gate_type)
• random_qprog(qubits, depth, gate_type, topology)

topology is an edge list in the same format as ChipInfo.get_chip_topology(), for example [[0, 1], [1, 2]]. Every two-qubit gate emitted by the generator lands on one of the given edges; single-qubit gates are unrestricted. If an edge references a qubit outside qubits, the function raises ValueError.

from pyqpanda3.core import random_qcircuit, random_qprog

topology = [[0, 1], [1, 2]]
circ = random_qcircuit([0, 1, 2], 5, ["H", "CNOT"], topology)
prog = random_qprog([0, 1, 2], 5, ["H", "CNOT"], topology)
print(circ.gate_operations())
print(prog.gate_operations())

5. GPUQVM accepts an initial state

GPUQVM.init_state(state) installs the initial state vector used by subsequent run() calls; its length must be a power of two, and init_state([]) restores the default |0...0>. Without a call to init_state, the simulator starts from |0...0>. Invalid lengths, NaN/Inf amplitudes, and non-normalized states raise RuntimeError.

GPUQVM is available only in CUDA builds; in a build without CUDA, pyqpanda3.core.GPUQVM is None (an ImportWarning is emitted at import time) and cannot be constructed. Use simulator_capabilities("GPUQVM").available to check whether the current build provides the backend.

from pyqpanda3.core import GPUQVM, QProg, measure

qvm = GPUQVM()
qvm.init_state([0, 1])          # |1>
prog = QProg(1)
prog << measure(0, 0)
qvm.run(prog, 16)
print(qvm.result().get_counts())  # {'1': 16}

NOTE

The example above requires a CUDA-enabled pyqpanda3 build and was not executed locally.

6. Other fixes and stability improvements

• The photonic pilot backend merges consecutive single-qubit gates instead of emitting a separate U3 for each one.
• Transpiler memory reclamation and build-stability improvements.
• Additional regression tests for API contracts, random-circuit topology, QVM initial states, and QCloud API-key domains.

API changes

Interface	0.5.1 change
QCloudService(api_key)	New single-argument constructor; resolves the service domain from a new-format key
QCloudService(api_key, url)	url no longer has a default value; explicitly overrides the domain encoded in the key
QCloudOptions(...)	Supports keyword construction
QCloudOptions.set_amend_flag / amend_flag	New; 0/1/3
QCloudOptions.set_use_cz_pattern / use_cz_pattern	New
QCloudJob.result()	Server-reported task failures no longer raise RuntimeError; returns a FAILED result; transport-level errors may still be raised
random_qcircuit(..., topology)	New overload
random_qprog(...)	New function, with a topology overload
GPUQVM.init_state(state)	New

Upgrade notes

• Code that used try/except RuntimeError to catch server-reported task failures should instead check job_status() == JobStatus.FAILED and read error_message().
• Transport-layer exceptions remain: network, protocol, or HTTP errors may still be raised by the underlying request, so keep the try/except handling for them.
• QCloudService(api_key, url=...) still works; the single-argument form now connects using the domain encoded in the key.
• Only control flow that relied on result() raising needs to change.