quafu

Classes:

Name	Description
Task	This guide provides the essential steps to get started with QuarkStudio for accessing the Quafu Superconducting Quantum Computing Cloud.

Task(token: str = '')

Bases: object

This guide provides the essential steps to get started with QuarkStudio for accessing the Quafu Superconducting Quantum Computing Cloud.

---

🚀 Getting Started

1.Installation

Ensure you have Python 3.12 or higher installed. Then, install the package using pip:

pip install -U quarkstudio

2. Authentication

You need a personal token to access the platform. 1. Get a Token: SQCLab website. Keep your token secure and do not share it, as it expires after 30 days. 2. Initialize:

from quark import Task
tmgr = Task('your_token_here')

---

⚙️ Core Workflow

1. Check Backend Status

Before submitting, check the queue status of available quantum processors (backends):

print(tmgr.status())

Output example:

{'Dongling': 0,      # No tasks queued
'Baihua': 10,     # 10 tasks queued
'Miaofeng': 'Offline' # Backend unavailable
}

2. Submit a Quantum Task

Define your task as a dictionary. Your quantum circuit must be written in OpenQASM 2.0.

task = {
'chip': 'Dongling',  # chip name
'name': 'MyJob',  # task name
'circuit': circuit, # circuit written in OpenQASM2.0
'shots': 1024, # an integer multiple of 1024
'options':{
    'compiler': None|'quarkcircuit'|'qsteed'|'qiskit', # defaults to 'quarkcircuit'
    'correct': False, # readout error correction 
    'open_dd': None|'XY4'|'CPMG', # dynamial decoupling,  # defaults to None
    'target_qubits': [] # [0, 1]
}
}

Submit the task asynchronously. You will receive a Task ID (tid) immediately.

tid = tmgr.run(task)
print(tid)  # e.g., 2024041917095371986

Note: Users can submit up to 1000 tasks per day. Excess tasks will be queued for the next day.

3. Retrieve Results

Use the tid to get your results. The result is a dictionary containing the measurement counts and task metadata.

result = tmgr.result(tid)
print(result['count'])  # Dictionary of measurement results
print(result['status']) # e.g., 'Finished'

Methods:

Name	Description
run	run a task

Source code in quark/quafu.py

def __init__(self, token: str = '') -> None:
    self.token = os.getenv('QPU_API_TOKEN', token)
    assert self.token, f'token is required, get it from SQCLab[{self.URL}]!'

    v = self.verify()
    if isinstance(v, dict):
        raise Exception(f'{v}')

    self.tasks = {}
    self.cache = {}

run(task: dict, repeat: int = 1)

run a task

Parameters:

Name	Type	Description	Default
task	dict	task description.	required

Returns:

Name	Type	Description
int		task id

Source code in quark/quafu.py

def run(self, task: dict, repeat: int = 1):
    """run a task

    Args:
        task (dict): task description.

    Returns:
        int: task id
    """
    time.sleep(0.2)
    name = task.get('name', 'MyQuantumJob')
    chip = task['chip']
    shots = task.get('shots', repeat * 1024)
    circuit = str(task['circuit'])
    tid = self.request(f'{self.URL}/task/run/?name={name}&chip={chip}&shots={shots}',
                       data={'circuit': circuit,
                             'compile': task.get('compile', True),
                             'options': task.get('options', {
                                 'clientip': os.getenv('CLIENT_REAL_IP', '')
                             })},
                       method='post')
    if isinstance(tid, int):
        self.tasks[tid] = task
    return tid