附录D：SDK函数说明

1.0.4(20231007)

本地快速安装SDK环境，请使用如下指令：

pip install --upgrade ezQgd -i  https://pypi.tuna.tsinghua.edu.cn/simple

如遇国内源暂未同步，请强行指定国外源进行更新安装-i https://pypi.org/simple

__init__(self, login_key=None, machine_name=None) special

accout initialization

Parameters:

Name	Type	Description	Default
login_key	Optional[str]	API Token under personal center on the web. Defaults to None.. Defaults to None.	None
machine_name	Optional[str]	name of quantum computer. Defaults to None.	None

Exceptions:

Type	Description
Exception	throw an exception when login fails

assign_parameters(self, circuits, parameters, values)

Check if the number of parameters, values match the circuit definition

Parameters:

Name	Type	Description	Default
circuits	List[str]	string, QCIS circuit definition with or without parameter place holder	required
parameters	List[List]	list or ndarray of strings, parameters to be filled	required
values	List[List]	list or ndarray of floats, values to be assigned	required

Returns:

Type	Description
circuit	circuit with parameters replaced by values or empty string empty string occurs when errors prevents parameters to be assigned

convert_qasm_to_qcis(self, qasm, qubit_map=None)

convert qasm to qcis.

Parameters:

Name	Type	Description	Default
qasm	str	qasm.	required
qubit_map	Optional[Dict]	Number mapping in qasm, where the value is None, directly maps bits based on the format of number plus 1. Defaults to None.	None

Exceptions:

Type	Description
Exception	language conversion failed.

Returns:

Type	Description
str	simplified qcis.

convert_qasm_to_qcis_from_file(self, qasm_file, qubit_map=None)

Read qasm from file and convert it to qcis

Parameters:

Name	Type	Description	Default
qasm_file	str	qasm file.	required
qubit_map	Optional[Dict]	Number mapping in qasm, where the value is None, directly maps bits based on the format of number plus 1. Defaults to None.	None

Exceptions:

Type	Description
Exception	language conversion failed.

Returns:

Type	Description
str	simplified qcis.

convert_qcis_to_qasm(self, qcis)

convert qcis to qasm.

Parameters:

Name	Type	Description	Default
qcis	str	qcis	required

Returns:

Type	Description
str	converted qasm.

create_experiment(self, exp_name, remark='测试')

create a new experiment, the new one is the experiment set ID.

Parameters:

Name	Type	Description	Default
exp_name	str	new experiment collection Name.	required
remark	Optional[str]	experimental remarks. Defaults to 测试.	'测试'

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, success returns the experimental set id

current_time(self)

get the current time

Returns:

Type	Description
str	time string

download_config(self, read_time=None, down_file=True)

download experimental parameters.

Parameters:

Name	Type	Description	Default
read_time		select configuration data according to the reading time, and the parameter format is yyyy-MM-dd HHss, Defaults to None.	None
down_file	Optional[bool]	the parameter is True to write to the file, and False to directly return the experimental parameters. Defaults to True.	True

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, success returns the experimental parameters.

get_experiment_circuit(self, query_id)

according to the exp_id obtained experimental circuit

Parameters:

Name	Type	Description	Default
query_id	Union[str, List[str]]	the result returned by the run_experiment interface, experimental set id.	required

The maximum number of experimental line queries supported by the server is 50. If it exceeds 50, an error message will be displayed.

Returns:

Type	Description
Union[int, List[Dict]]	0 failed, not 0 successful, success returns the experimental circuit, The parameters of the returned experimental circuit include qcis、mapQcis and computerQcis, qcis is the line submitted by the user, mapQcis is the compiled circuit, computerQcis is a circuit submitted to a quantum computer.

get_experiment_data(self, circuit)

Parse circuit description and generate experiment script and extract number of measured qubits.

Parameters:

Name	Type	Description	Default
circuit	str	string, QCIS circuit	required

Returns:

Type	Description
expData	string, transformed circuit

log_in(self)

Authenticate username and password and return user credit

Returns int: log in state, 1 means pass authentication, 0 means failed

probability_calibration(self, result, config_json=None)

correction of the measured probability of 01 quantum state.

Parameters:

Name	Type	Description	Default
result	Dict	the results returned after query_experiment.	required
config_json	Optional[Dict]	experimental parameters of quantum computer. config_json value is None, read the latest experimental parameters for calculation. Defaults to None.	None

Exceptions:

Type	Description
Exception	cannot calibrate probability with fidelity.

Returns:

Type	Description
Dict	corrected probability.

probability_correction(self, probabilities)

correction of the measured probability of 01 quantum state. If there is a probability greater than 1, change this item to 1. If there is anything less than 0, change the item to 0.

Parameters:

Name	Type	Description	Default
probabilities		corrected probability.	required

Returns:

Type	Description
Dict	corrected probability.

qcis_check_regular(self, qcis_raw)

qcis regular check,normal returns 1, abnormal returns 0

Parameters:

Name	Type	Description	Default
qcis_raw	str	qcis	required

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, successfully returned the input qics.

qcis_mapping_isq(self, qcis_circuit, initial_layout=None, objective='size', seed=None, use_post_opt=False)

The script transpiles qcis string by searching for a mapping from virtual to physical qubit and a swap strategy such that the circuit described by qcis can be fitted into a hardware described by the coupling_map, in the meanwhile reduces circuit depth.

Parameters:

Name	Type	Description	Default
qcis_circuit	str	qcis circuit	required
initial_layout	Optional[Dict]	Initial position of virtual qubits on physical qubits. If given, this is the initial state in search of virtual to physical qubit mapping e.g.: {0:4, 1:1, 2:5, 3:2, 4:0, 5:3}. Defaults to None.	None
objective	Optional[str]	an error if fail. Defaults to 'size'.	'size'
seed	Optional[int]	Set random seed for the stochastic part of the tranpiler. Defaults to None.	None
use_post_opt	Optional[bool]	we provide a genetic alg. which utilizes exchange rules for swaps to futher min. depth. Defaults to False.	False

Raised

Transpileerror

if graph specified by coupling map is disconnected.

Returns:

Type	Description
str	qcis string after transpilation

qcis_mapping_sabre(self, qcis_circuit)

The script transpiles qcis string by searching for a mapping from virtual to physical qubit and a swap strategy such that the circuit described by qcis can be fitted into a hardware described by the coupling_map, in the meanwhile reduces circuit depth.

Parameters:

Name	Type	Description	Default
qcis_circuit	str	qcis circuit	required

Returns:

Type	Description
str	qcis after mapping

query_experiment(self, query_id, max_wait_time=60)

query experimental results

Parameters:

Name	Type	Description	Default
query_id	Union[str, List[str]]	the result returned by the run_experiment interface, experimental set id	required
max_wait_time	Optional[int]	maximum waiting time for querying experiments. Defaults to 60.	60

Description

The maximum number of experimental result queries supported by the server is 50. If there are more than 50, an error message will be displayed.

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, success returns the experimental result

readout_data_to_state_probabilities_part(self, result)

read data and convert it into a quantum state probability, do not return with a probability of 0.

Parameters:

Name	Type	Description	Default
result	Dict	the results returned after query_experiment.	required

Returns:

Type	Description
Dict	probability

readout_data_to_state_probabilities_whole(self, result)

read data and convert it into a quantum state probability, all returns.

Parameters:

Name	Type	Description	Default
result	Dict	the results returned after query_experiment.	required

Returns:

Type	Description
Dict	probability

run_experiment(self, exp_id, num_shots=12000, is_verify=True)

running the experiment returns the query result id.

Parameters:

Name	Type	Description	Default
exp_id	str	the result returned by the save_experiment interface, experimental id	required
num_shots	Optional[int]	number of repetitions per experiment. Defaults to 12000.	12000
is_verify	Optional[bool]	Is the circuit verified.True verify, False do not verify. Defaults to True.	True

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, success returns the query id

save_experiment(self, lab_id, exp_data, name='detailtest', language='qcis')

save the experiment and return the experiment ID.

Parameters:

Name	Type	Description	Default
lab_id	str	the result returned by the create_experiment interface, experimental set id	required
exp_data	str	experimental content, qics	required
name	Optional[str]	experimental Details Name. Defaults to "detailtest".	'detailtest'
language	Optional[str]	Quantum computer language, including ['isq', 'quingo', 'qcis']. Defaults to "qcis".	'qcis'

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, success returns the experiment id.

set_machine(self, machine_name)

set the machine name.

Parameters:

Name	Type	Description	Default
machine_name	str	name of quantum computer.	required

simplify(self, qcis_raw)

simplification of qcis lines.

Parameters:

Name	Type	Description	Default
qcis_raw	str	qcis	required

Returns:

Type	Description
str	simplified qcis.

submit_job(self, circuit=None, exp_name='exp0', parameters=None, values=None, num_shots=12000, lab_id=None, exp_id=None, version='version01', is_verify=True)

submit experimental tasks

Parameters:

Name	Type	Description	Default
circuit	Union[List, str]	experimental content, qics. Defaults to None.	None
exp_name	Optional[str]	new experiment collection Name. Defaults to 'exp0'.	'exp0'
parameters	Optional[List[List]]	parameters that need to be assigned in the experimental content. Defaults to None.	None
values	Optional[List[List]]	The values corresponding to the parameters that need to be assigned in the experimental content. Defaults to None.	None
num_shots	Optional[int]	number of repetitions per experiment. Defaults to 12000.	12000
lab_id	Optional[str]	the result returned by the create_experiment interface, experimental set id. Defaults to None.	None
exp_id	Optional[str]	the result returned by the save_experiment interface, experimental id. Defaults to None.	None
version	Optional[str]	version description. Defaults to 'version01'.	'version01'
is_verify	Optional[bool]	Is the circuit verified.True verify, False do not verify. Defaults to True.	True

Description

There are some parameter range limitations when using batch submission circiuts. 1. circuits length less than 50 numshots maximum 100000 the number of measurement qubits is less than 15 2. circuits length greater than 50 but less than 100 numshots maximum 50000 the number of measurement qubits is less than 30 3. circuits length greater than 100 but less than 600 numshots maximum 10000 the number of measurement bits is less than the number of all available qubits 4. When the circuit is none, the exp_id cannot be none and the lab_id needs to be none, 5. When the circuit is not none, when the circuit is multiple lines, the version and exp_id need to be none, and the line will be saved under the default collection if the lab_id or exp_name is not transmitted. 6. When the circuit is not none, when the circuit is a single line, exp_id need none, version does not transmit to generate the default, lab_id or exp_name does not transmit the line is saved under the default collection.

Description

1. When the circuit is none, the exp_id cannot be none and the lab_id needs to be none,
2. When the circuit is not none, when the circuit is multiple lines, the version and exp_id need to be none, and the line will be saved under the default collection if the lab_id or exp_name is not transmitted.
3. When the circuit is not none, when the circuit is a single line, exp_id need none, version does not transmit to generate the default, lab_id or exp_name does not transmit the line is saved under the default collection.

Returns:

Type	Description
Union[int, str]	0 failed, not 0 successful, success returns the query id.