QPilotServiceBase

QPilotServiceBase is the main service class for interacting with the QPilot OS quantum computing platform. It provides methods for submitting quantum programs, querying results, and managing tasks on various backends including simulators and real quantum chips.

Signature

python

QPilotServiceBase(url: str, log_cout: bool = False, api_key: str = None)
QPilotServiceBase(url: str, log_cout: bool = False, username: str = None, password: str = None)

Parameters

Parameter	Type	Default	Description
url	str	required	URL of the QPilot OS server
log_cout	bool	False	Whether to log output to console
api_key	str	None	API key for authentication
username	str	None	Username for credential-based authentication
password	str	None	Password for credential-based authentication

Two authentication modes are supported: API key-based and username/password-based.

Methods

Configuration

init_config

python

init_config(url: str, log_cout: bool) -> None

Initializes or reconfigures the service connection.

Parameter	Type	Description
url	str	QPilot OS server URL
log_cout	bool	Whether to enable console logging

get_token

python

get_token(rep_json: str) -> str

Extracts an authentication token from a JSON response string.

Parameter	Type	Description
rep_json	str	JSON response from the authentication endpoint

Message Building

build_init_msg

python

build_init_msg(api_key: str) -> str

Builds an initialization message for authentication with the QPilot OS server.

Parameter	Type	Description
api_key	str	API key for authentication

build_task_msg

python

build_task_msg(prog: QProg, shot: int, chip_id: str, is_amend: bool,
               is_mapping: bool, is_optimization: bool,
               specified_block: list[int], task_describe: str,
               point_lable: int, priority) -> str

Builds a real chip measurement task message body.

Parameter	Type	Description
prog	QProg	The quantum program
shot	int	Number of execution shots
chip_id	str	Target chip identifier
is_amend	bool	Whether to apply amendment
is_mapping	bool	Whether to apply qubit mapping
is_optimization	bool	Whether to apply circuit optimization
specified_block	list[int]	Specified block constraints
task_describe	str	Task description
point_lable	int	Point label for the task
priority	int	Task priority level

build_task_proto_msg

python

build_task_proto_msg(shot: int, chip_id: str, is_amend: bool,
                     is_mapping: bool, is_optimization: bool,
                     specified_block: list[int], task_describe: str,
                     task_type, point_lable: int, priority) -> str

Builds a real chip measurement task message using protocol buffer format.

build_expectation_task_msg

python

build_expectation_task_msg(prog: QProg, hamiltonian,
                           qubits: list[int] = [], shot: int = 1000,
                           chip_id: str = "any_quantum_chip",
                           is_amend: bool = True, is_mapping: bool = True,
                           is_optimization: bool = True,
                           specified_block: list[int] = [],
                           task_describe: str = "") -> str

Builds an expectation value task message for Hamiltonian expectation computation.

Parameter	Type	Default	Description
prog	QProg	required	The quantum program
hamiltonian	Hamiltonian	required	Target Hamiltonian
qubits	list[int]	[]	Qubit subset for computation
shot	int	1000	Number of execution shots
chip_id	str	"any_quantum_chip"	Target chip identifier
is_amend	bool	True	Apply amendment
is_mapping	bool	True	Apply qubit mapping
is_optimization	bool	True	Apply optimization
specified_block	list[int]	[]	Block constraints
task_describe	str	""	Task description

build_qst_task_msg

python

build_qst_task_msg(prog: QProg, shot: int = 1000,
                   chip_id: str = "any_quantum_chip",
                   is_amend: bool = True, is_mapping: bool = True,
                   is_optimization: bool = True,
                   specified_block: list[int] = [],
                   task_describe: str = "") -> str

Builds a Quantum State Tomography (QST) task message.

build_query_msg

python

build_query_msg(task_id: str) -> str

Builds a query message for checking task status.

Parameter	Type	Description
task_id	str	The task identifier to query

Execution -- Synchronous

run

Submits a quantum program and waits for the result. Multiple overloads accept QProg, str (OriginIR), list[QProg], or list[str] as input.

python

# Single program
run(prog: QProg, shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# Single OriginIR string
run(ir: str, shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# Multiple programs
run(prog: list[QProg], shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# Multiple OriginIR strings
run(ir: list[str], shot: int = 1000, chip_id: str = "any_quantum_chip",
    is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
    specified_block: list[int] = [], describe: str = "",
    point_lable: int = 0) -> str

# With configuration string
run(prog: list[QProg], config_str: str) -> str

Parameter	Type	Default	Description
prog	QProg or list[QProg]	required	Quantum program(s) to execute
ir	str or list[str]	required	OriginIR string(s) to execute
shot	int	1000	Number of execution shots
chip_id	str	"any_quantum_chip"	Target chip identifier
is_amend	bool	True	Apply amendment
is_mapping	bool	True	Apply qubit mapping
is_optimization	bool	True	Apply circuit optimization
specified_block	list[int]	[]	Block constraints
describe	str	""	Task description
point_lable	int	0	Point label
config_str	str	required	JSON configuration string

Returns: The result as a string.

run_simulator

python

def run_simulator(prog: QProg, shot: int) -> dict[str, float]

python

def run_simulator(prog: QProg, qubit_vec: list[int]) -> dict[str, float]

Runs a quantum program on the local simulator.

Parameter	Type	Description
prog	QProg	The quantum program to simulate
shot	int	Number of measurement shots
qubit_vec	list[int]	Qubits to measure (partial measurement)

real_chip_measure_prob_count

Submits a real chip measurement job and returns probability counts. Supports QProg, str, list[QProg], and list[str] inputs.

python

real_chip_measure_prob_count(prog: QProg, shot: int = 1000,
                            chip_id: str = "any_quantum_chip",
                            is_mapping: bool = True, is_optimization: bool = True,
                            specified_block: list[int] = [], describe: str = "",
                            point_lable: int = 0) -> str

Parameter	Type	Default	Description
prog	QProg or str or list	required	Quantum program(s) or OriginIR
shot	int	1000	Number of shots
chip_id	str	"any_quantum_chip"	Target chip
is_mapping	bool	True	Apply qubit mapping
is_optimization	bool	True	Apply circuit optimization
specified_block	list[int]	[]	Block constraints
describe	str	""	Task description
point_lable	int	0	Point label

real_chip_expectation

python

real_chip_expectation(prog: QProg, hamiltonian, qubits: list[int] = [],
                      shot: int = 1000, chip_id: str = "any_quantum_chip",
                      is_amend: bool = True, is_mapping: bool = True,
                      is_optimization: bool = True,
                      specified_block: list[int] = [],
                      describe: str = "") -> str

Computes the expectation value of a Hamiltonian on a real chip. This method is deprecated; use the run or async_run methods instead.

Execution -- Asynchronous

async_run

Submits a quantum program and returns immediately with a task ID. Supports the same input types as run, with an additional is_prob_counts parameter.

python

# Single program
async_run(prog: QProg, shot: int = 1000, chip_id: str = "any_quantum_chip",
          is_amend: bool = True, is_mapping: bool = True, is_optimization: bool = True,
          specified_block: list[int] = [], is_prob_counts: bool = True,
          describe: str = "", point_lable: int = 0) -> str

# With configuration string
async_run(prog: list[QProg], config_str: str) -> str

Parameter	Type	Default	Description
prog	QProg or str or list	required	Quantum program(s) or OriginIR
shot	int	1000	Number of shots
chip_id	str	"any_quantum_chip"	Target chip
is_amend	bool	True	Apply amendment
is_mapping	bool	True	Apply qubit mapping
is_optimization	bool	True	Apply optimization
specified_block	list[int]	[]	Block constraints
is_prob_counts	bool	True	Return probability counts
describe	str	""	Task description
point_lable	int	0	Point label
config_str	str	required	JSON configuration string

Returns: A task ID string for later querying.

async_real_chip_expectation

python

async_real_chip_expectation(prog: QProg, hamiltonian, qubits: list[int] = [],
                            shot: int = 1000, chip_id: str = "any_quantum_chip",
                            is_amend: bool = True, is_mapping: bool = True,
                            is_optimization: bool = True,
                            specified_block: list[int] = [],
                            describe: str = "") -> str

Asynchronous Hamiltonian expectation value computation on a real chip. This method is deprecated; use async_run instead.

Quantum State Tomography

async_real_chip_qst

python

async_real_chip_qst(prog: QProg, shot: int = 1000,
                    chip_id: str = "any_quantum_chip",
                    is_amend: bool = True, is_mapping: bool = True,
                    is_optimization: bool = True,
                    specified_block: list[int] = [],
                    describe: str = "", point_lable: int = 0) -> str

Submits an asynchronous Quantum State Tomography task. Returns a task ID.

async_real_chip_qst_density

python

async_real_chip_qst_density(prog: QProg, shot: int = 1000,
                            chip_id: str = "any_quantum_chip",
                            is_amend: bool = True, is_mapping: bool = True,
                            is_optimization: bool = True,
                            specified_block: list[int] = [],
                            describe: str = "", point_lable: int = 0) -> str

Submits an asynchronous QST density matrix computation task. Returns a task ID.

async_real_chip_qst_fidelity

python

async_real_chip_qst_fidelity(prog: QProg, shot: int = 1000,
                             chip_id: str = "any_quantum_chip",
                             is_amend: bool = True, is_mapping: bool = True,
                             is_optimization: bool = True,
                             specified_block: list[int] = [],
                             describe: str = "", point_lable: int = 0) -> str

Submits an asynchronous QST fidelity computation task. Returns a task ID.

Error Mitigation

noise_learning

python

noise_learning(parameter_json: str) -> str

Submits a noise learning task with the given JSON parameters.

em_compute

python

em_compute(parameter_json: str) -> str

Runs error mitigation computation synchronously with the given JSON parameters.

async_em_compute

python

async_em_compute(parameter_json: str) -> str

Submits an error mitigation computation task asynchronously.

Result Retrieval

query_result

python

query_result(task_id: str) -> list
query_result(task_id: str, is_save: bool, file_path: str = "") -> list

Queries the result of a task by its ID.

Parameter	Type	Default	Description
task_id	str	required	The task identifier
is_save	bool	required	Whether to save the result to a file
file_path	str	""	File path for saving results

Returns: A list [state, result_vec, err_code, err_info] where:

state (str): Task state -- "2" for Running, "3" for Finished, "4" for Failed
result_vec (list): Result data strings
err_code (ErrorCode): Error code if any
err_info (str): Error information string

query_task_state_vec

python

query_task_state_vec(task_id: str) -> list

Queries the task state and result vector. Returns the same format as query_result.

query_compile_prog

python

query_compile_prog(task_id: str, without_compensate: bool = True) -> list

Queries the compiled program for a given task.

Parameter	Type	Default	Description
task_id	str	required	The task identifier
without_compensate	bool	True	Whether to return the program without angle compensation

Returns: A list [err_code, err_info, compile_prog].

get_measure_result

python

get_measure_result(task_id: str) -> list

Retrieves the measurement result for a completed task.

Returns: A list [result, err_code, err_info] where result is a list of dictionaries mapping state strings to measurement values.

get_expectation_result

python

get_expectation_result(task_id: str) -> list

Retrieves the expectation value result for a completed task.

Returns: A list [expectation, err_code, err_info] where expectation is a float.

_get_qst_result

python

_get_qst_result(task_id: str) -> list

Retrieves the QST measurement result for a completed task.

Returns: A list [result, err_code, err_info].

_get_qst_density_result

python

_get_qst_density_result(task_id: str) -> list

Retrieves the QST density matrix result.

Returns: A list [density, err_code, err_info].

_get_qst_fidelity_result

python

_get_qst_fidelity_result(task_id: str) -> list

Retrieves the QST fidelity result.

Returns: A list [fidelity, err_code, err_info] where fidelity is a float.

Result Parsing

parse_task_result

python

parse_task_result(result_str: str) -> dict[str, float]

Parses a result string into a dictionary mapping state strings to floating-point values.

parse_probability_result

python

parse_probability_result(result_str: list[str]) -> list[dict[str, float]]

Parses a list of result strings into a list of dictionaries with probability values.

parse_prob_counts_result

python

parse_prob_counts_result(result_str: list[str]) -> list[dict[str, int]]

Parses a list of result strings into a list of dictionaries with integer count values.

parser_sync_result

python

parser_sync_result(json_str: str) -> list[dict[str, float]]

Parses a synchronous result JSON string into probability data.

parser_expectation_result

python

parser_expectation_result(json_str: str) -> list[list[float]]

Parses an expectation value result JSON string. This method is deprecated; use Python's json library instead.

Network

tcp_recv

python

tcp_recv(ip: str, port: int, task_id: str) -> list

Receives task results via TCP connection.

Parameter	Type	Description
ip	str	TCP server IP address
port	int	TCP server port
task_id	str	Task identifier to retrieve

Returns: A list [is_ok, response] where is_ok is a boolean and response is the result string.

Utility

output_version

python

output_version() -> str

Returns the version string of the QPilot OS service.

Examples

python

from pyqpanda3.pilot_service import QPilotService
from pyqpanda3.core import QCircuit, H, CNOT, measure

# Initialize with API key
service = QPilotService(
    url="https://qpilot.originquantum.cn",
    api_key="your_api_key"
)

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

# Synchronous execution
result = service.run(prog, shot=1000, chip_id="simulation")

# Asynchronous execution
task_id = service.async_run(prog, shot=1000, chip_id="real_chip")

# Query result
result_dict = service.query_result(task_id)
print(f"State: {result_dict['taskState']}, Results: {result_dict['taskResult']}")

# Parse results
if result_dict['taskState'] == "3":  # Finished
    parsed = service.parse_probability_result(result_dict['taskResult'])
    print(f"Parsed results: {parsed}")

QPilotServiceBase ​

Signature ​

Parameters ​

Methods ​

Configuration ​

init_config ​

get_token ​

Message Building ​

build_init_msg ​

build_task_msg ​

build_task_proto_msg ​

build_expectation_task_msg ​

build_qst_task_msg ​

build_query_msg ​

Execution -- Synchronous ​

run ​

run_simulator ​

real_chip_measure_prob_count ​

real_chip_expectation ​

Execution -- Asynchronous ​

async_run ​

async_real_chip_expectation ​

Quantum State Tomography ​

async_real_chip_qst ​

async_real_chip_qst_density ​

async_real_chip_qst_fidelity ​

Error Mitigation ​

noise_learning ​

em_compute ​

async_em_compute ​

Result Retrieval ​

query_result ​

query_task_state_vec ​

query_compile_prog ​

get_measure_result ​

get_expectation_result ​

_get_qst_result ​

_get_qst_density_result ​

_get_qst_fidelity_result ​

Result Parsing ​

parse_task_result ​

parse_probability_result ​

parse_prob_counts_result ​

parser_sync_result ​

parser_expectation_result ​

Network ​

tcp_recv ​

Utility ​

output_version ​

Examples ​

See Also ​

QPilotServiceBase

Signature

Parameters

Methods

Configuration

init_config

get_token

Message Building

build_init_msg

build_task_msg

build_task_proto_msg

build_expectation_task_msg

build_qst_task_msg

build_query_msg

Execution -- Synchronous

run

run_simulator

real_chip_measure_prob_count

real_chip_expectation

Execution -- Asynchronous

async_run

async_real_chip_expectation

Quantum State Tomography

async_real_chip_qst

async_real_chip_qst_density

async_real_chip_qst_fidelity

Error Mitigation

noise_learning

em_compute

async_em_compute

Result Retrieval

query_result

query_task_state_vec

query_compile_prog

get_measure_result

get_expectation_result

_get_qst_result

_get_qst_density_result

_get_qst_fidelity_result

Result Parsing

parse_task_result

parse_probability_result

parse_prob_counts_result

parser_sync_result

parser_expectation_result

Network

tcp_recv

Utility

output_version

Examples

See Also