qpanda3_runtime.runtime_service#

Classes#

RuntimeService

QPanda3 Runtime Service Client Manager Class.

Module Contents#

class qpanda3_runtime.runtime_service.RuntimeService(url_or_cfgfile: str = 'https://qpanda3-runtime.qpanda.cn', trace_record_file: str = None, auto_track: bool = False)#

Bases: qpanda3_runtime.toolbox.tracker.TrackerSystem

QPanda3 Runtime Service Client Manager Class.

Manages user requests and response data for quantum runtime services.

Parameters:

  • url_or_cfgfile (str) – Either a URL address or a path to a YAML configuration file. - URL: Quantum runtime server access address (e.g., ‘https://localhost:8080’) - File path: YAML file containing server URL and API key credentials

  • trace_record_file (str, optional) – Path to trace record file for tracking operations. Required if auto_track is True.

  • auto_track (bool, optional) – Whether to automatically track operations. Default is False.

Variables:

  • tokens (dict) – Currently logged-in compute backend access channels and their corresponding access tokens.

  • base_url (str) – QPanda3 Runtime server URL.

Examples

Method 1: Direct URL

>>> service = RuntimeService('https://localhost:8080')

Method 2: Configuration file

>>> # config.yml
... api_key: '9B41FB6534584E45BD6BE0E6'
... server_url: 'https://localhost:8080'
>>> service = RuntimeService(r'config.yml')
tokens#

Currently logged-in compute backend access channels and their corresponding access tokens.

base_url = None#

QPanda3 Runtime server URL

login(api_key, channel: str = default_channel)#

Authenticate to the specified compute backend access channel.

Parameters:

  • api_key (str) – API key credentials for authentication.

  • channel (str, optional) – Compute backend access channel. Default is default_channel.

Returns:

Access token for the specified compute backend.

Return type:

str

Raises:

RuntimeError – If authentication fails or server returns unexpected response.

Examples

>>> service = RuntimeService('https://localhost:8080')
>>> token = service.login('9B41FB6534584E45BD6BE0E6')
query_task(channel: str, task_id: list, additional_info: List[str] | None = None, using_http=True, timeout: float = 600)#

Query execution results and related information for specified compute tasks.

Parameters:

  • channel (str) – Compute backend access channel.

  • task_id (List[str]) – List of subtask IDs uniquely identifying the compute task.

  • additional_info (Optional[List[str]], optional) – Additional query fields for task execution information. Refer to compute backend documentation for available fields.

  • using_http (bool, optional) – Protocol to use for query transmission. - True: Use HTTP protocol (default) - False: Use TCP protocol

Returns:

Execution results and related information for each task.

Return type:

list

Raises:

RuntimeError – If channel is not logged in or query fails.

list_devices(channel=default_channel, target: int | str = '')#

List quantum computing devices available on the specified compute backend.

Parameters:

  • channel (str, optional) – Compute backend access channel. Default is default_channel.

  • target (Union[int, str], optional) – Single device ID to retrieve. If empty, returns all devices.

Returns:

  • If target is empty: List of all available QDevice objects

  • If target is specified: Single QDevice object for the specified device

Return type:

Union[List[QDevice], QDevice]

Raises:

RuntimeError – If target device is not available or server returns unexpected response.

query_device_config(dev: qpanda3_runtime.device.qdevice.QDevice)#

Query configuration and parameter information of the specified quantum computing device.

Parameters:

dev (QDevice) – Quantum computing device to query.

Returns:

Device configuration and parameter information, including: - Quantum topology structure - Noise statistics (T1, T2, readout error rates) - Other device-specific parameters

Return type:

dict

Raises:

RuntimeError – If query fails or server returns unexpected response.

sample(circuits: qpanda3_runtime.utils.union_type.QProgUnionType | List[qpanda3_runtime.utils.union_type.QProgUnionType] | qpanda3_runtime.task.program_set.gate_params_bind_rule.AnsatzParamsBinding | Tuple[pyqpanda3.vqcircuit.VQCircuit, List[numpy.ndarray]], device: qpanda3_runtime.device.qdevice.QDevice | qpanda3_runtime.device.fake_backend.FakeBackend, measure_qubits: List[int] | None = None, specified_block: List[int] | None = None, shots: int = 10, is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True, point_label: int = 0, task_describe: str = '') → qpanda3_runtime.task.qtask_manager.QTaskManager#

Submit sampling computation task to quantum runtime server.

Core quantum computing operation for sampling measurement results.

Parameters:

  • circuits (Union[QProgUnionType, List[QProgUnionType], AnsatzParamsBinding, Tuple[VQCircuit, List[numpy.ndarray]]]) – Quantum circuits for sampling task. - QProgUnionType: Single quantum program - List[QProgUnionType]: Multiple quantum programs - AnsatzParamsBinding: Parameterized ansatz circuits - Tuple[VQCircuit, List[numpy.ndarray]]: VQCircuit with parameter arrays

  • device (Union[QDevice, FakeBackend]) – Quantum computing device. - QDevice: Real quantum computer/chip - FakeBackend: Local simulation with noise models

  • measure_qubits (Optional[List[int]], optional) – Qubits to measure. If circuit has measurement nodes, replaces them. If circuit has no measurement nodes, must be provided.

  • specified_block (Optional[List[int]], optional) – Physical qubit indices to use. Empty list enables automatic selection.

  • shots (int, optional) – Number of sampling trials. Default is 10.

  • is_amend (bool, optional) – Enable error mitigation amendment. Default is True.

  • is_mapping (bool, optional) – Enable qubit mapping. Default is True.

  • is_optimization (bool, optional) – Enable circuit optimization. Default is True.

  • point_label (int, optional) – Currently disabled parameter.

  • task_describe (str, optional) – Currently disabled parameter.

Returns:

Local task manager for monitoring and retrieving results.

Return type:

QTaskManager

Raises:

RuntimeError – If parameters are invalid or task submission fails.

estimate(circuit_with_observable: Tuple[qpanda3_runtime.utils.union_type.QProgUnionType | List[qpanda3_runtime.utils.union_type.QProgUnionType], qpanda3_runtime.utils.union_type.ObservableUnionType] | qpanda3_runtime.task.program_set.observable_bind_rule.CircuitObservableBinding | qpanda3_runtime.task.program_set.observable_bind_rule.AnsatzObservableBinding, device: qpanda3_runtime.device.qdevice.QDevice | qpanda3_runtime.device.fake_backend.FakeBackend, specified_block: List[int] | None = None, shots: int = 1000, is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True, task_describe: str = '') → qpanda3_runtime.task.qtask_manager.QTaskManager#

Submit Hamiltonian expectation estimation task to quantum runtime server.

Core quantum computing operation for estimating observable expectations.

Parameters:

  • circuit_with_observable (Union[Tuple[Union[QProgUnionType, List[QProgUnionType]], ObservableUnionType], CircuitObservableBinding, AnsatzObservableBinding]) – Quantum circuits and observables for expectation estimation. - Tuple: (circuit(s), observable) - CircuitObservableBinding: Pre-bound circuit-observable pairs - AnsatzObservableBinding: Parameterized ansatz with observables

  • device (Union[QDevice, FakeBackend]) – Quantum computing device. - QDevice: Real quantum computer/chip - FakeBackend: Local simulation with noise models

  • specified_block (Optional[List[int]], optional) – Physical qubit indices to use. Empty list enables automatic selection.

  • shots (int, optional) – Number of sampling trials. Default is 1000.

  • is_amend (bool, optional) – Enable error mitigation amendment. Default is True.

  • is_mapping (bool, optional) – Enable qubit mapping. Default is True.

  • is_optimization (bool, optional) – Enable circuit optimization. Default is True.

  • task_describe (str, optional) – Currently disabled parameter.

Returns:

Local task manager for monitoring and retrieving results.

Return type:

QTaskManager

Raises:

RuntimeError – If parameters are invalid or task submission fails.

get_task(task_id: str | List[str], channel=default_channel)#

Create local task management object for existing computation tasks.

Parameters:

  • task_id (Union[str, List[str]]) – Computation task ID(s). - str: Single task ID - List[str]: Collection of subtask IDs

  • channel (str, optional) – Backend access channel where the task resides. Default is default_channel.

Returns:

Local task management object for monitoring and retrieving results.

Return type:

QTaskManager

Notes

This method creates a management object for tasks already submitted to the runtime server.

device(chip_id: int | str, channel=default_channel) → qpanda3_runtime.device.qdevice.QDevice#

Create local management object for quantum computing device.

Parameters:

  • chip_id (Union[int, str]) – Device identifier.

  • channel (str, optional) – Backend access channel. Default is default_channel.

Returns:

Local device management object.

Return type:

QDevice

Raises:

RuntimeError – If chip_id is empty or device creation fails.

fake_backend(real_device: qpanda3_runtime.device.qdevice.QDevice, channel='local_simulator', noise_info: dict | None = None) → qpanda3_runtime.device.fake_backend.FakeBackend#

Create FakeBackend for local simulation of real quantum device.

Parameters:

  • real_device (QDevice) – Real quantum computer/chip to simulate.

  • channel (str, optional) – Simulation channel. Currently must be ‘local_simulator’.

  • noise_info (Union[dict, None], optional) – Noise model dictionary for simulation. - None: Use noise data from corresponding real device - dict: Custom noise model parameters

Returns:

Local simulation backend with noise models.

Return type:

FakeBackend

static transpile_safe(prog: str, chip_topology_edges: List[List[int]], basic_gates: List[str], compensate_angle_map_json: str, specified_block: List[int], optim_level: int)#

Transpile quantum circuits using multi-processing for exception isolation.

This method executes locally on the client side and must be called within __name__ == ‘__main__’ environment due to Python multiprocessing restrictions.

Parameters:

  • prog (str) – Quantum circuit to transpile (OriginIR format).

  • chip_topology_edges (List[List[int]]) – Physical qubit topology edges of the quantum computing backend.

  • basic_gates (List[str]) – Basic quantum gates supported at physical level.

  • compensate_angle_map_json (str) – Compensation angle mapping data in JSON format.

  • specified_block (List[int]) – Physical qubit indices for circuit placement. Empty list enables automatic selection.

  • optim_level (int) – Transpilation optimization level.

Returns:

Transpiled quantum circuit in OriginIR format.

Return type:

str

Raises:

RuntimeError – If transpilation fails or times out.

Notes

For detailed documentation, refer to: - https://qcloud.originqc.com.cn/document/qpanda-3/cn/d3/df1/tutorial_quantum_circuit_transpiler.html - https://qcloud.originqc.com.cn/document/qpanda-3/cn/d7/d65/tutorial_quantum_program_of_content__origin_i_r.html

vqsession(vqcircuit: pyqpanda3.vqcircuit.VQCircuit, device: qpanda3_runtime.device.qdevice.QDevice | qpanda3_runtime.device.fake_backend.FakeBackend, shots=1000, life_time=360, observable: qpanda3_runtime.utils.union_type.ObservableUnionType | None = None)#

Request variational quantum computing session from runtime service.

Parameters:

  • vqcircuit (VQCircuit) – Variational quantum circuit (Ansatz structure) for parameterized circuits.

  • device (Union[QDevice, FakeBackend]) – Quantum computing device for the session. - QDevice: Real quantum computer/chip - FakeBackend: Local simulation

  • shots (int, optional) – Number of sampling trials per circuit. Default is 1000.

  • life_time (float, optional) – Session lifespan in seconds. Default is 360.

  • observable (Union[ObservableUnionType, None], optional) – Observable for expectation estimation tasks.

Returns:

Local session management object.

Return type:

Union[VQSession, FakeVQSession]

Notes

Use the with statement to manage VQSession context lifecycle.

run_vqtask(session_id, gate_params, measure_list: list = [], channel=default_channel, return_type: str = 'QTaskManager')#

Add quantum computing task to variational computing session.

Parameters:

  • session_id (str) – Variational computing session ID.

  • gate_params (array-like) – Quantum gate parameters for Ansatz structure.

  • measure_list (list, optional) – Qubit indices to measure. Default is empty list.

  • channel (str, optional) – Access channel to quantum computing device. Default is default_channel.

  • return_type (str, optional) – Return value type control. - ‘QTaskManager’: Returns QTaskManager object (default) - Other: Returns dictionary with task information

Returns:

Task management object or task information dictionary.

Return type:

Union[QTaskManager, dict]

Raises:

RuntimeError – If session is invalid or task submission fails.

release_session(session_id: str, chip_id: str, channel: str = default_channel)#

Release quantum runtime service session.

Parameters:

  • session_id (str) – Quantum runtime service session ID.

  • chip_id (str) – Quantum runtime service chip ID ID.

  • channel (str, optional) – Access channel of the session. Default is default_channel.

Returns:

Server response data.

Return type:

dict

Raises:

RuntimeError – If session release fails.

recover_qtask_manager(checkpoint_file: str, recover_completely: bool = True) → qpanda3_runtime.task.qtask_manager.QTaskManager#

Recover QTaskManager object from checkpoint file.

Parameters:

  • checkpoint_file (str) – Checkpoint file path.

  • recover_completely (bool, optional) – Recovery mode. - True: Complete recovery, task_state must contain all information (default) - False: Partial recovery, allow default values for missing fields

Returns:

Recovered task management object.

Return type:

QTaskManager

Raises:

  • FileNotFoundError – If checkpoint file does not exist.

  • ValueError – If recover_completely is True and task_state is missing required fields.

  • RuntimeError – Other exceptions during recovery process.