QCloudService

QCloudService is the main entry point for connecting to the OriginQ quantum cloud platform. It manages authentication and provides access to available quantum backends.

Signature

python

QCloudService(api_key: str, url: str = DEFAULT_URL)

Parameters

Parameter	Type	Default	Description
api_key	str	required	API key for authenticating with the cloud service
url	str	DEFAULT_URL	URL of the cloud service endpoint

Methods

setup_logging

python

setup_logging(output: LogOutput = LogOutput.CONSOLE, file_path: str = "") -> None

Configures the logging system for the cloud service.

Parameter	Type	Default	Description
output	LogOutput	CONSOLE	Destination for log output (CONSOLE or FILE)
file_path	str	""	File path for saving logs when output is FILE

backends

python

backends() -> dict[str, bool]

Returns a dictionary of available backends on the cloud platform, where keys are backend names and values indicate availability.

Returns: A dictionary mapping backend names to their availability status.

backend

python

backend(backend_name: str) -> QCloudBackend

Retrieves a specific backend by its name for running quantum programs.

Parameter	Type	Description
backend_name	str	The name of the backend to retrieve

Returns: A QCloudBackend object for the specified backend.

Examples

python

from pyqpanda3.qcloud import QCloudService, LogOutput

# Initialize the cloud service
service = QCloudService(api_key="your_api_key")

# Optionally configure logging to a file
service.setup_logging(output=LogOutput.FILE, file_path="qcloud.log")

# List all available backends
for name in service.backends():
    print(name)

# Get a specific backend
backend = service.backend("origin_simulation")

QCloudBackend

QCloudBackend represents a quantum backend (simulator or real chip) available on the cloud platform. It provides methods for submitting quantum programs and computing expectation values.

Signature

python

QCloudBackend(backend_name: str)

Parameters

Parameter	Type	Description
backend_name	str	The name of the quantum cloud backend

Methods

run

Submits a quantum program to the backend for execution. Multiple overloads are available.

Run with noise model

python

run(prog: QProg, shots: int, model: QCloudNoiseModel = QCloudNoiseModel(),
    batch_id: str = "", task_form: int = 4) -> QCloudJob

Parameter	Type	Default	Description
prog	QProg	required	The quantum program to run
shots	int	required	Number of execution shots
model	QCloudNoiseModel	QCloudNoiseModel()	Noise model for simulation
batch_id	str	""	Batch identifier for grouping jobs
task_form	int	4	Task form identifier

Run on specified qubits

python

run(prog: QProg, qubits: list[int], batch_id: str = "", task_form: int = 4) -> QCloudJob

Parameter	Type	Default	Description
prog	QProg	required	The quantum program to run
qubits	list[int]	required	Qubits to run the program on
batch_id	str	""	Batch identifier
task_form	int	4	Task form identifier

Run with QCloudOptions

python

run(prog: QProg, shots: int, options: QCloudOptions,
    enable_binary_encoding: bool = False, batch_id: str = "",
    task_form: int = 4) -> QCloudJob

Parameter	Type	Default	Description
prog	QProg	required	The quantum program to run
shots	int	required	Number of execution shots
options	QCloudOptions	required	Execution configuration options
enable_binary_encoding	bool	False	Whether to use binary encoding
batch_id	str	""	Batch identifier
task_form	int	4	Task form identifier

Run multiple programs

python

run(progs: list[QProg], shots: int, options: QCloudOptions,
    enable_binary_encoding: bool = False, batch_id: str = "",
    task_form: int = 4) -> QCloudJob

Parameter	Type	Default	Description
progs	list[QProg]	required	List of quantum programs to run
shots	int	required	Number of execution shots
options	QCloudOptions	required	Execution configuration options
enable_binary_encoding	bool	False	Whether to use binary encoding
batch_id	str	""	Batch identifier
task_form	int	4	Task form identifier

Run for amplitude computation

python

run(prog: QProg, amplitudes: list[str]) -> QCloudJob
run(prog: QProg, amplitude: str) -> QCloudJob

Parameter	Type	Description
prog	QProg	The quantum program to run
amplitudes	list[str]	List of amplitude state names to compute
amplitude	str	Single amplitude state name to compute

run_instruction

python

run_instruction(instruction: str, shots: int, options: QCloudOptions,
                batch_id: str = "", task_form: int = 4) -> QCloudJob
run_instruction(instructions: list[str], shots: int, options: QCloudOptions,
                batch_id: str = "", task_form: int = 4) -> QCloudJob

Runs a quantum instruction (JSON string) or list of instructions on the backend.

Parameter	Type	Default	Description
instruction	str	required	A JSON string representing a quantum instruction
instructions	list[str]	required	A list of JSON instruction strings
shots	int	required	Number of shots to execute
options	QCloudOptions	required	Configuration options
batch_id	str	""	Batch identifier
task_form	int	4	Task form identifier

run_quantum_state_tomography

python

run_quantum_state_tomography(prog: QProg, shots: int,
                             options: QCloudOptions = False) -> QCloudJob

Runs quantum state tomography on the given program.

Parameter	Type	Default	Description
prog	QProg	required	The quantum program
shots	int	required	Number of execution shots
options	QCloudOptions	False	Execution options

expval_hamiltonian

python

expval_hamiltonian(prog: QProg, hamiltonian: Hamiltonian, shots: int = 1000,
                   noise_model: QCloudNoiseModel = QCloudNoiseModel()) -> float
expval_hamiltonian(prog: QProg, hamiltonian: Hamiltonian,
                   options: QCloudOptions) -> float

Computes the expectation value of a Hamiltonian with respect to the given quantum program.

Parameter	Type	Default	Description
prog	QProg	required	The quantum program to execute
hamiltonian	Hamiltonian	required	The Hamiltonian for expectation value computation
shots	int	1000	Number of sampling shots
noise_model	QCloudNoiseModel	QCloudNoiseModel()	Noise model for simulation
options	QCloudOptions	required	Execution configuration (alternative overload)

Returns: The expectation value as a float.

expval_pauli_operator

python

expval_pauli_operator(prog: QProg, pauli_operator: PauliOperator, shots: int = 1000,
                      noise_model: QCloudNoiseModel = QCloudNoiseModel()) -> float
expval_pauli_operator(prog: QProg, pauli_operator: PauliOperator,
                      options: QCloudOptions) -> float

Computes the expectation value of a Pauli operator with respect to the given quantum program.

Parameter	Type	Default	Description
prog	QProg	required	The quantum program to execute
pauli_operator	PauliOperator	required	The Pauli operator for expectation value computation
shots	int	1000	Number of sampling shots
noise_model	QCloudNoiseModel	QCloudNoiseModel()	Noise model for simulation
options	QCloudOptions	required	Execution configuration (alternative overload)

Returns: The expectation value as a float.

chip_info

python

chip_info() -> ChipInfo

Retrieves the chip configuration and topology information for this backend.

Returns: A ChipInfo object containing chip properties.

chip_backend

python

chip_backend(qubits: list[int] = []) -> ChipBackend

Retrieves the backend configuration for this chip, optionally filtered by a subset of qubits.

Parameter	Type	Default	Description
qubits	list[int]	[]	Optional list of qubit indices to filter the backend configuration

Returns: A ChipBackend object containing the chip backend configuration. Import from pyqpanda3.transpilation.

name

python

name() -> str

Retrieves the name of the backend.

Returns: The backend name string.

Examples

python

from pyqpanda3.qcloud import QCloudService, QCloudNoiseModel, QCloudOptions
from pyqpanda3.core import QCircuit, H, CNOT, measure

service = QCloudService(api_key="your_api_key")
backend = service.backend("origin_simulation")

# Create and run a simple circuit
circuit = QCircuit(2)
circuit << H(0) << CNOT(0, 1)
prog = QProg()
prog << circuit << measure([0, 1], [0, 1])

# Run with default settings
job = backend.run(prog, shots=1000)

# Run with custom options
options = QCloudOptions()
options.set_mapping(True)
options.set_optimization(True)
job = backend.run(prog, shots=1000, options=options)

# Run with noise model
noise = QCloudNoiseModel()
job = backend.run(prog, shots=1000, model=noise)

# Compute expectation value
from pyqpanda3.hamiltonian import Hamiltonian
result = backend.expval_hamiltonian(prog, hamiltonian, shots=2000)
print(f"Expectation value: {result}")

QCloudOptions

QCloudOptions configures execution options for cloud quantum jobs, including mapping, optimization, amendment, and custom parameters.

Signature

python

QCloudOptions()

Methods

Setters

Method	Signature	Description
set_amend	`set_amend(is_amend: bool) -> None`	Enable or disable amendment
set_mapping	`set_mapping(is_mapping: bool) -> None`	Enable or disable qubit mapping
set_optimization	`set_optimization(is_optimization: bool) -> None`	Enable or disable circuit optimization
set_point_label	`set_point_label(label: int) -> None`	Set the point label for real chip tasks
set_specified_block	`set_specified_block(block) -> None`	Set the specified block for real chip tasks
set_is_prob_counts	`set_is_prob_counts(is_prob_counts: bool) -> None`	Set whether to return probability counts
set_custom_option	`set_custom_option(key: str, value) -> None`	Set a custom option (int, double, string, or bool)

Getters

Method	Signature	Description
is_amend	`is_amend() -> bool`	Check if amendment is enabled
is_mapping	`is_mapping() -> bool`	Check if mapping is enabled
is_optimization	`is_optimization() -> bool`	Check if optimization is enabled
point_label	`point_label() -> int`	Get the point label value
is_prob_counts	`is_prob_counts() -> bool`	Get whether probability counts are enabled
specified_block	`specified_block() -> list`	Get the specified block value

Custom Options

Method	Signature	Description
get_custom_option	`get_custom_option(key: str) -> int/float/str/bool`	Retrieve a custom option by key (type depends on stored value)
has_custom_option	`has_custom_option(key: str) -> bool`	Check whether a custom option exists
get_custom_options	`get_custom_options() -> dict`	Retrieve all custom options as a dictionary

Utility

Method	Signature	Description
print	`print() -> None`	Print the current options settings to standard output

Examples

python

from pyqpanda3.qcloud import QCloudOptions

options = QCloudOptions()
options.set_amend(True)
options.set_mapping(True)
options.set_optimization(True)
options.set_point_label(0)
options.set_custom_option("custom_key", 42)

print("Amend:", options.is_amend())
print("Has custom:", options.has_custom_option("custom_key"))
print("Custom value:", options.get_custom_option("custom_key"))

options.print()

ChipInfo

ChipInfo contains detailed information about a quantum chip, including qubit properties, topology, and gate configurations.

Signature

python

ChipInfo()

Note: ChipInfo objects are typically obtained from QCloudBackend.chip_info() rather than constructed directly.

Methods

Method	Signature	Description
qubits_num	`qubits_num() -> int`	Number of qubits on the chip
chip_id	`chip_id() -> str`	The chip identifier string
available_qubits	`available_qubits() -> list[int]`	Indices of available qubits
high_frequency_qubits	`high_frequency_qubits() -> list[int]`	Indices of high-frequency qubits
single_qubit_info	`single_qubit_info() -> list[SingleQubitInfo]`	Per-qubit property information
double_qubits_info	`double_qubits_info() -> list[DoubleQubitsInfo]`	Qubit pair gate information
get_basic_gates	`get_basic_gates() -> list`	List of basic gates supported by the chip
get_compensate_angle_map	`get_compensate_angle_map() -> dict`	Compensate angle map for calibration
get_single_gate_timing	`get_single_gate_timing() -> int`	Single-qubit gate timing
get_double_gate_timing	`get_double_gate_timing() -> int`	Two-qubit gate timing
get_chip_topology	`get_chip_topology(qubits: list[int] = []) -> list`	Chip topology edges, optionally filtered by qubits
get_chip_backend	`get_chip_backend(qubits: list[int] = []) -> ChipBackend`	Backend configuration, optionally filtered by qubits

Examples

python

backend = service.backend("origin_quantum_chip")
info = backend.chip_info()

print(f"Chip: {info.chip_id()}")
print(f"Qubits: {info.qubits_num()}")
print(f"Available qubits: {info.available_qubits()}")

for qinfo in info.single_qubit_info():
    print(f"  Qubit {qinfo.get_qubit_id()}: T1={qinfo.get_t1()}, T2={qinfo.get_t2()}, "
          f"fidelity={qinfo.get_single_gate_fidelity()}")

SingleQubitInfo

Properties of a single qubit on a quantum chip.

Methods

Method	Signature	Description
get_qubit_id	`get_qubit_id() -> str`	The qubit identifier
get_single_gate_fidelity	`get_single_gate_fidelity() -> float`	Single-qubit gate fidelity
get_readout_fidelity	`get_readout_fidelity() -> float`	Readout measurement fidelity
get_frequency	`get_frequency() -> float`	Qubit frequency
get_t1	`get_t1() -> float`	T1 relaxation time
get_t2	`get_t2() -> float`	T2 coherence time

DoubleQubitsInfo

Properties of a qubit pair used for two-qubit gate operations.

Signature

python

DoubleQubitsInfo(qubit1: int, qubit2: int, fidelity: float)

Methods

Method	Signature	Description
get_qubits	`get_qubits() -> list[int]`	The pair of qubit indices
get_fidelity	`get_fidelity() -> float`	Two-qubit gate fidelity for this pair

ChipBackend

Low-level backend configuration for a quantum chip, including topology, gate information, and timing parameters.

Note: ChipBackend is exported from pyqpanda3.transpilation, not from pyqpanda3.qcloud. Import it as from pyqpanda3.transpilation import ChipBackend.

Signature

python

ChipBackend()
ChipBackend(chip_topology_edges: list[list[int]], basic_gates: list[str],
            compensate_angle_map: dict, echo_gate_timing: int,
            barrier_gate_timing: int, single_gate_timing: int,
            double_gate_timing: int, patterns: dict)

Attributes

Attribute	Type	Description
chip_topology_edges	list[list[int]]	Topology edges of the chip
basic_gates	list[str]	List of supported basic gate names
compensate_angle_map	dict	Map from qubit pairs to compensate angles
echo_gate_timing	int	Timing for echo gates
barrier_gate_timing	int	Timing for barrier gates
single_gate_timing	int	Timing for single-qubit gates
double_gate_timing	int	Timing for two-qubit gates
patterns	dict	CZ gate patterns

QCloudService ​

Signature ​

Parameters ​

Methods ​

setup_logging ​

backends ​

backend ​

Examples ​

QCloudBackend ​

Signature ​

Parameters ​

Methods ​

run ​

Run with noise model ​

Run on specified qubits ​

Run with QCloudOptions ​

Run multiple programs ​

Run for amplitude computation ​

run_instruction ​

run_quantum_state_tomography ​

expval_hamiltonian ​

expval_pauli_operator ​

chip_info ​

chip_backend ​

name ​

Examples ​

QCloudOptions ​

Signature ​

Methods ​

Setters ​

Getters ​

Custom Options ​

Utility ​

Examples ​

ChipInfo ​

Signature ​

Methods ​

Examples ​

SingleQubitInfo ​

Methods ​

DoubleQubitsInfo ​

Signature ​

Methods ​

ChipBackend ​

Signature ​

Attributes ​

See Also ​

QCloudService

Signature

Parameters

Methods

setup_logging

backends

backend

Examples

QCloudBackend

Signature

Parameters

Methods

run

Run with noise model

Run on specified qubits

Run with QCloudOptions

Run multiple programs

Run for amplitude computation

run_instruction

run_quantum_state_tomography

expval_hamiltonian

expval_pauli_operator

chip_info

chip_backend

name

Examples

QCloudOptions

Signature

Methods

Setters

Getters

Custom Options

Utility

Examples

ChipInfo

Signature

Methods

Examples

SingleQubitInfo

Methods

DoubleQubitsInfo

Signature

Methods

ChipBackend

Signature

Attributes

See Also