SpinQLab Link Package

Spinqlablink is a Python package used to connect and control quantum devices, providing an interface to interact with SpinQ quantum experimental equipment. This package allows users to perform various quantum experiments, including system initialization, quantum gate operations, quantum circuit construction, and quantum algorithm implementation.

Main Functions

• Device connection and management

• Quantum experiment execution and control

• Quantum gates and quantum circuits construction

• Pulse sequence definition and operation

• Implementation of quantum algorithm

Basic Usage

from spinqlablink import SpinQLabLink

# Create connection
spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")

# Connect to device
spinqlablink.connect()

# Wait for login to complete
if not spinqlablink.wait_for_login():
    print("Login failed")
    return

# Disconnect after use
spinqlablink.disconnect()

public function

class spinqlablink.SpinQLabLink(host, port, account, password)

The SpinQLabLink class is the core component of the package and is responsible for managing connections to quantum devices, experimental execution and result acquisition.

Parameters:

• host (str) – Device host address

• port (int) – Device port number

• account (str) – user account

• password (str) – user password

connect()

Connect to quantum devices.

Returns:

a successful connection

Return type:

bool

disconnect()

Disconnect the connection from the quantum device.

Returns:

Whether the disconnection was successful

Return type:

bool

wait_for_login(timeout=10)

Wait for login to complete, the timeout time is 10 seconds.

Parameters:

timeout (int) – Time-out (seconds)

Returns:

Whether the login was successful

Return type:

bool

get_device()

Gets a device object that is used to access device parameters and status.

Returns:

Device Object

Return type:

Device

register_experiment(experiment_type)

Sign up for a new experiment.

Parameters:

experiment_type (ExperimentType) – Experiment Type

Returns:

Experimental objects and parameters

Return type:

tuple

run_experiment()

Run registered experiments.

wait_for_experiment_completion()

Wait for the experiment to complete.

Returns:

Whether the experiment was successfully completed

Return type:

bool

get_experiment_result()

Obtain experimental results.

Returns:

Experimental Results

Return type:

dict

deregister_experiment()

Log out of the current experiment.

Returns:

Whether the logout was successful

Return type:

bool

get_device_status()

Get device status.

Returns:

device status information

Return type:

dict

get_device_frequencies()

Get device frequency information.

Returns:

Equipment frequency information

Return type:

dict

Experiment Type

class spinqlablink.ExperimentType

The ExperimentType enumeration defines the types of experiments available.

Attribute	Description
NMR_PHENOMENON_AND_SIGNAL	Pulse Sequence Experiment
RABI_OSCILLATIONS	Rabi oscillation experiment
QUANTUM_BIT	qubit operation
QUANTUM_DECOHERENCE_T1	T1 relaxation measurement
QUANTUM_DECOHERENCE_T2	T2 relaxation measurement
QUANTUM_CONTROL	quantum control experiment
QUANTUM_SYSTEM_INITIALIZATION	Quantum system initialization
QUANTUM_GATES_AND_CIRCUIT	Quantum gates and quantum circuit operations
QUANTUM_STATE_TOMOGRAPHY	quantum state chromatography
QUANTUM_COMPUTING_TASK	quantum computational tasks
INTRODUCTION_TO_QUANTUM_COMPUTING	Basic experiments of quantum computing
DEUTSCH_ALGORITHM	Deutsch algorithm experiment
BERNSTEIN_VARIRANI_ALGORITHM	Bernstein-Vazirani algorithm experiment
GROVER_ALGORITHM	Grover algorithm experiment
QFT_ALGORITHM	QFT algorithm experiment
HHL_ALGORITHM	HHL algorithm experiment
VQE_ALGORITHM	VQE algorithm experiment
QAOA_ALGORITHM	QAOA algorithm experiment
SPIN_ECHO	spin echo experiment
DYNAMIC_DECOUPLING	dynamic decoupling experiment
SHAPE_PULSE	shape pulse experiment
NUMERICAL_OPTIMIZATION_PULSE	Numerical optimization pulse experiment
PHYSICAL_LAYER_EXPERIMENT	physical layer experiment
CIRCUIT_LAYER_EXPERIMENT	Circuit layer experiment

pulse operation

class spinqlablink.Pulse(path, phase, amplitude, width, detuning=0)

The Pulse class is used to define the pulse sequence for quantum operations.

Parameters:

• path (int) – Pulse path (0 represents hydrogen channel, 1 represents phosphorus channel)[0,1]

• phase (float) – Pulse phase (degrees)[0,360]

• amplitude (float) – Pulse amplitude (percentage)[0,100]

• width (float) – Pulse width (microseconds)[0,200000]

• detuning (float) – Pulse frequency offset (Hz)[0,10000]

from spinqlablink import Pulse

# Create a pulse
pulse = Pulse(path=0, phase=90, amplitude=100, width=40)

class spinqlablink.Gradient(path, amplitude, width)

The Gradient class is used to define gradient pulses.

Parameters:

• path (int) – Gradient path, default to 1

• amplitude (float) – Gradient amplitude [0,100]

• width (float) – Gradient width (microseconds)[0,200000]

Quantum gates and circuits

class spinqlablink.Gate(type, qubitIndex=0, controlQubit=-1, controlQubit2=-1, delay=0, angle=0)

The Gate class is used to define quantum gate operations.

Parameters:

• type (str) – Gate types (e.g.,’H’,’ X’,’Y’,’ Z’,’CNOT’, etc.)[‘H’,’ I’,’X’,’ Y’,’Z’,’ X90’,’Y90’,’ Z90’,’Rx’,’ Ry’,’Rz’,’ Td’,’Sd’,’CNOT’,’ CZ’]

• qubitIndex (int) – qubit indexing

• controlQubit (int) – Control qubit indexing (for control gates such as CNOT)

• angle (float) – Door angle (degrees)[0,360]

• delay (float) – Gate delay (microseconds)[0,200000]

• timeslot (int) – Gate time slot [0,60]

• controlQubit2 (int) – Second control qubit index (for CNOT gates)

from spinqlablink import Gate

# Create a Hadamard gate acting on qubit 0
h_gate = Gate(type='H', qubitIndex=0)

# create a Rx gate with angle 90 degrees
rx_gate = Gate(type='Rx', qubitIndex=0, angle=90)

# Create a CNOT gate with control qubit 0 and target qubit 1
cnot_gate = Gate(type='CNOT', qubitIndex=1, controlQubit=0)

class spinqlablink.CustomGate(type, customType, pulses=None, gateJson=None)

The CustomGate class is used to define custom quantum gates.

Parameters:

• type (str) – Gate types (e.g.,’H’,’ X’,’Y’,’ Z’, etc.)[‘H’,’ I’,’X’,’ Y’,’Z’,’ X90’,’Y90’,’ Z90’,’Rx’,’ Ry’,’Rz’,’ Td’,’Sd’,’CNOT’,’ CZ’]

• customType (str) – Custom door type name

• pulses (list[Pulse]) – List of pulse sequences

• gateJson (str) – JSON string for door definition

---

Example of a JSON string defined by gateJson:

Note: After reading the json file, the input is in string form. Do not use the json.loads() function

{
   "description": {
      "TITLE": "H2_custom_gate.spinq",
      "TYPE": "",
      "ORIGIN": "",
      "OWNER": "",
      "DATE": "",
      "TIME": "",
      "TOTALPULSEWIDTH": 0,
      "Calibration_Power": 0,
      "SLICES": 0,
      "PULSEWIDTH": 40
   },
   "pulse": {
      "channel1_pulse": [
         {
               "detuning": 0,
               "phase": 90.0,
               "amplitude": 100.0,
               "width": 40.0
         }
      ],
      "channel2_pulse": [
         {
               "detuning": 0,
               "phase": 0.0,
               "amplitude": 0.0,
               "width": 40.0
         }
      ]
   }
}

---

Example definition of CustomGate:

from spinqlablink import CustomGate, Pulse

# Define a custom Hadamard gate using pulse sequences
custom_h_gate = CustomGate(
    type='H',
    customType='H_custom_gate',
    pulses=[Pulse(path=0, phase=90, amplitude=100, width=40)]
)

# Define a custom Hadamard gate using JSON definition (alternative method)
custom_x_gate = CustomGate(
    type='X',
    customType='X_custom_gate',
    gateJson="{\"description\":{\"TITLE\":\"H2_custom_gate.spinq\",\"TYPE\":\"\",\"ORIGIN\":\"\",\"OWNER\":\"\",\"DATE\":\"\",\"TIME\":\"\",\"TOTALPULSEWIDTH\":0,\"Calibration_Power\":0,\"SLICES\":0,\"PULSEWIDTH\":40},\"pulse\":{\"channel1_pulse\":[{\"detuning\":0,\"phase\":90.0,\"amplitude\":100.0,\"width\":40.0}],\"channel2_pulse\":[{\"detuning\":0,\"phase\":0.0,\"amplitude\":0.0,\"width\":40.0}]}}"
)

class spinqlablink.Circuit(qubit_count)

The Circuit class is used to build quantum circuits.

Parameters:

qubit_count (int) – Number of qubits

__lshift__(gate)

Add quantum gates to the circuit.

Parameters:

gate (Gate or CustomGate) – Quantum gates to add

Returns:

The circuit object itself

Return type:

Circuit

print_circuit()

Print the circuit structure.

from spinqlablink import Circuit, Gate, CustomGate, Pulse

# Create a 2-qubit circuit
circuit = Circuit(2)

# Add quantum gates
circuit << Gate(type='H', qubitIndex=0)
circuit << Gate(type='CNOT', qubitIndex=1, controlQubit=0)
circuit << CustomGate(
    type='X',
    customType='X_custom_gate',
    qubitIndex=0,
    pulses=[Pulse(path=0, phase=90, amplitude=100, width=80)]
)

# Print circuit structure
circuit.print_circuit()

utility

spinqlablink.print_graph(result)

Print a chart of experimental results.

Parameters:

result (dict) – Experimental Results

spinqlablink.parse_spinq_file(file_path)

Parse SpinQ files.

Parameters:

file_path (str) – file path

Returns:

analysis result

Return type:

dict

File formats See CustomGate for more details about the SpinQ file format.

spinqlablink.pulse_domain_analysis(pulses)

Perform domain analysis on the pulse sequence.

Parameters:

pulses (list[Pulse]) – pulse sequence

Returns:

analysis results

Return type:

dict

class spinqlablink.WaveformGenerator

Waveform generator class, used to generate various waveforms.

generate_gaussian(amplitude, width, sigma)

Generate a Gaussian waveform.

Parameters:

• amplitude (float) – amplitude

• width (float) – width

• sigma (float) – standard deviation

Returns:

waveform data

Return type:

list[float]

generate_square(amplitude, width)

Generate square waves.

Parameters:

• amplitude (float) – amplitude

• width (float) – width

Returns:

waveform data

Return type:

list[float]

uses examples

System Initialization Experiment

from spinqlablink import SpinQLabLink, ExperimentType, Pulse

# Create connection
spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
spinqlablink.connect()

if not spinqlablink.wait_for_login():
    print("Login failed")
    return

# Register system initialization experiment
_, exp_sysinit_para = spinqlablink.register_experiment(ExperimentType.QUANTUM_SYSTEM_INITIALIZATION)

# Set experiment parameters
exp_sysinit_para.repeat = 9
exp_sysinit_para.pulses = [
    Pulse(path=0, phase=90, amplitude=100, width=40),
    # More pulses...
]

# Run experiment
spinqlablink.run_experiment()
spinqlablink.wait_for_experiment_completion()

# Get results
result = spinqlablink.get_experiment_result()

# Cleanup
spinqlablink.deregister_experiment()
spinqlablink.disconnect()

Quantum Algorithm Experiment

from spinqlablink import SpinQLabLink, ExperimentType, Gate, Circuit

# Create connection
spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
spinqlablink.connect()

if not spinqlablink.wait_for_login():
    print("Login failed")
    return

# Register quantum algorithm experiment
_, exp_algorithm_para = spinqlablink.register_experiment(ExperimentType.QUANTUM_ALGORITHM)

# Set algorithm type
exp_algorithm_para.algorithm_type = ExperimentType.INTRODUCTION_TO_QUANTUM_COMPUTING
exp_algorithm_para.samplePath = -1

# Create quantum circuit
circuit = Circuit(2)
circuit << Gate(type='H', qubitIndex=0)
circuit << Gate(type='CNOT', qubitIndex=1, controlQubit=0)

# Set circuit
exp_algorithm_para.set_circuit(circuit)

# Run experiment
spinqlablink.run_experiment()
spinqlablink.wait_for_experiment_completion()

# Get results
result = spinqlablink.get_experiment_result()

# Cleanup
spinqlablink.deregister_experiment()
spinqlablink.disconnect()

Device Data Monitoring

from spinqlablink import SpinQLabLink

# Data update callback function
def on_info_update(device, update_type):
    if update_type == 'status':
        print(f"Device status update: Connected={device.status.connected}, Lock={device.status.lock_state}")
    elif update_type == 'lock_data':
        print(f"Lock data update: Frequency0={device.lock_data.frequency0} Hz")

# Create connection
spinqlablink = SpinQLabLink("192.168.15.4", 8181, "username", "password")
spinqlablink.connect()

if not spinqlablink.wait_for_login():
    print("Login failed")
    return

# Get device object and register observer
device = spinqlablink.get_device()
device.register_observer(on_info_update)

# Get device parameters
print("Pulse phases:", device.get_pulse_phases())
print("Qubit parameters:", device.get_qubit_params())

# Cleanup
device.unregister_observer(on_info_update)
spinqlablink.disconnect()