PLANQK Quantum Client Reference

The PLANQK Quantum Client is a Python SDK for accessing quantum computing backends through the PLANQK platform. It provides a low-level interface for direct interaction with quantum hardware and simulators, offering fine-grained control over job submission, backend management, and result retrieval.

The client is built on top of the PLANQK Quantum REST API, which you can explore here. For comprehensive examples and detailed documentation, please refer to the documentation and examples bundled with the SDK package.

This client allows you to:

• Discover and explore available quantum backends
• Submit quantum circuits using native gate formats
• Monitor job execution status and retrieve results
• Access detailed backend information and capabilities
• Manage quantum computing resources programmatically

Requirements

• Python 3.11 or higher
• Valid PLANQK access token

Installation

The package is published on PyPI and can be installed via pip:

pip install --upgrade planqk-quantum-client

Authentication

To use the SDK, you need to authenticate with your personal access token, which can be found on the PLANQK welcome page or generated in the settings.

Set your access token in one of the following ways:

1. Environment Variable: Set the PLANQK_PERSONAL_ACCESS_TOKEN environment variable. The SDK will automatically use it. Only for Python SDK.
2. Directly: Pass the token when creating the PlanqkQuantumClient.

Optionally, you can pass a organization ID, if you're working within a specific organization context.

Using the SDK

from planqk.quantum.client import PlanqkQuantumClient

# Create a client (authenticates via environment variable)
client = PlanqkQuantumClient()

# Or, pass the token directly
client = PlanqkQuantumClient(
    access_token="your_access_token_here",
    organization_id="your_org_id"  # Optional
)

Exploring Backends

Before submitting quantum jobs, you can discover and examine the available quantum backends. This includes checking their current status, capabilities, and specifications. For physical quantum hardware (non-simulators), you can also retrieve calibration data when supported by the backend.

# List all available backends
backends = client.backends.get_backends()
for backend in backends:
    console.log(f"{backend.id} - {backend.name}")

# Get detailed backend information
backend_info = client.backends.get_backend("aws.ionq.aria")
console.log(f"Backend: {backend_info.name}")
console.log(f"Qubits: {backend_info.configuration.qubit_count}")

# Check backend status and availability
status = client.backends.get_backend_status("azure.ionq.simulator")
console.log(f"Status: {status.status}")

# Get backend calibration data (for physical quantum hardware that supports it)
calibration = client.backends.get_backend_calibration("aws.ionq.aria")
console.log(f"Backend ID: {calibration.backend_id}")

Submitting a Quantum Job

Different quantum backends require different input formats and structures (see the Backend-Specific Input Classes table below). The PLANQK Quantum Client provides specific classes for each backend type to handle these format requirements. Each backend has its own input format class that defines the structure of quantum circuits or programs, and may also have specific input parameter classes for additional configuration.

This example demonstrates how to submit a quantum circuit using the IonQ native gate format. The circuit applies a Hadamard gate to the first qubit (creating a superposition) and an X gate to the second qubit (flipping it to |1⟩), resulting in the state |+1⟩.

from planqk.quantum.client.sdk import AzureIonqJobInput

# Define a quantum circuit using IonQ format
ionq_input = AzureIonqJobInput(
    gateset="qis",
    qubits=2,
    circuits=[
        {"type": "h", "targets": [0]},
        {"type": "x", "targets": [1], "controls": [0]},
    ]
)

# Submit job to a simulator
job = client.jobs.create_job(
    backend_id="azure.ionq.simulator",
    name="My Quantum Job",
    shots=100,
    input=ionq_input,
    input_params={},
    input_format="IONQ_CIRCUIT_V1"
)

console.log(f"Job submitted with ID: {job.id}")
console.log(f"Initial status: {job.status}")

Important: The client does not perform transpilation. Input must match the target backend's capabilities and connectivity, including gates, qubits, and other backend-specific requirements.

Backend-Specific Input Classes

The following table shows which input format and input parameter classes to use for each backend. Refer to this table when submitting jobs to ensure you're using the correct classes for your target backend. Each input format class also provides examples and documentation for the specific gate formats and circuit structures required by that backend.

Backend ID	Input Format Class	Input Params Class
azure.ionq.simulator	AzureIonqJobInput (IonQ API Qis v0.4 input)	None
aws.sim.dm1 aws.sim.sv1 aws.ionq.aria aws.ionq.aria-2 aws.ionq.forte aws.iqm.garnet aws.rigetti.ankaa	AwsQasm3JobInput (AWS Braket QASM3 string)	AwsQasm3JobInputParams (optional)

Monitoring Job Status and Retrieving Results

Once a job is submitted, you can monitor its execution status and retrieve results when the job completes. Jobs go through various states during their lifecycle, and you can check these states to understand the current execution phase.

Job States

Jobs can be in one of the following states:

• PENDING: Job is waiting to be executed
• RUNNING: Job is currently being executed on the backend
• COMPLETED: Job has finished successfully and results are available via job.results function.
• FAILED: Job execution failed due to an error. An error message can be retrieved via job.results function.
• CANCELLING: Job is being cancelled before completion
• CANCELLED: Job was cancelled before completion

Checking Job Status

# Get current job information
job_info = client.jobs.get_job(job.id)
console.log(f"Current status: {job_info.status}")

# You can also check specific job properties
console.log(f"Shots: {job_info.shots}")

Retrieving Results

When a job completes successfully, you can access the results. The result type is a dictionary whose structure depends on the backend being used.

# Wait for completion and get results
final_job = client.jobs.get_job(job_id)

if final_job.status == 'COMPLETED':
    results = client.jobs.get_job_result(job_id)
    console.log(f"Histogram: {results['histogram']}")
    # Expected output: {"00": ~50, "11": ~50} due to H gate on qubit 0 and X gate on qubit 1
   
    
elif final_job.status == 'FAILED':
    error = client.jobs.get_job_result(job_id)
    console.log(f"Job failed: {error}")

Polling for Completion

For jobs that may take time to complete, you can implement a polling mechanism:

import time

def wait_for_job_completion(client, job_id, poll_interval=5, timeout=300):
    """Poll job status until completion or timeout."""
    start_time = time.time()
    
    while time.time() - start_time < timeout:
        job = client.jobs.get_job(job_id)
        
        if job.status in ['COMPLETED', 'FAILED', 'CANCELLED']:
            return job
            
        console.log(f"Job {job_id} status: {job.status}")
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Job {job_id} did not complete within {timeout} seconds")

# Usage
completed_job = wait_for_job_completion(client, job.id)
console.log(f"Final status: {completed_job.status}")