Using the SDK

The PlanQK Quantum SDK provides an easy way for developing quantum circuits to be run on quantum devices provided by the PlanQK Platform. The SDK supports both the Qiskit 1.0 SDK and the Amazon Braket SDK, allowing you to choose your preferred framework for quantum programming. With Qiskit, you can access a wide range of quantum devices and simulators, while the Braket SDK expands your options by enabling the creation of Analog Hamiltonian Simulation (AHS) programs specifically for the QuEra Aquila quantum device.

Installation

You need to have Python 3.11 or higher installed. The package is released on PyPI and can be installed via pip:

pip install --upgrade planqk-quantum

NOTE

Ensure that you have versions older than Qiskit SDK 1.0 uninstalled before installing the PlanQK Quantum SDK. The best way to ensure this is to create a new virtual environment and install the PlanQK Quantum SDK there.

Execute your first circuit with Qiskit and Braket

In your Python code you can access the PlanQK quantum backends through the PlanqkQuantumProvider class. Import the class and instantiate it as shown below:

from planqk import PlanqkQuantumProvider

If you are already logged in with the PlanQK CLI you can create the provider object without any parameters:

provider = PlanqkQuantumProvider()

Alternatively, you can also create the provider object by passing your PlanQK personal access token:

provider = PlanqkQuantumProvider(access_token="your-access-token")

If you want to log in with your organization, you can additionally pass the organization id as a parameter. The organization id can be found in the organization settings on the PlanQK Platform:

provider = PlanqkQuantumProvider(organization_id="your-organization-id")

After you have created the provider object, you can list all backends supported by the PlanQK Platform and select the one you want to use. The available backends and their ids can be also found here:

# List all available PlanQK quantum backends
backends = provider.backends()

# Select a certain backend
backend = provider.get_backend("azure.ionq.simulator")

Based on the specified backend id, the method returns either a Qiskit backend object or a Braket device object:

• Qiskit backend objects: These come with functions and properties familiar from Qiskit 1.0, providing a consistent experience for those already accustomed to Qiskit's API.
• Braket backend objects: These objects align with the Braket SDK, offering functions and properties specific to Braket's framework.

NOTE

Access to IonQ's quantum simulator is available with Basic accounts. If you try to access other backends, an error is returned stating that accessing the resource is not allowed on a Basic account.

To access other QPUs, either you or your organization must have a Pro account. To upgrade to a Pro account, log in to your Account settings, click Upgrade, and select the Subscribe button under the Pro section. Follow the prompts to enter your payment details.

Working with Qiskit Backends

Now you can execute your Qiskit circuit on the selected backend, retrieve its job object, retrieve its results, cancel it etc. The full example would look like this:

from planqk import PlanqkQuantumProvider
from qiskit import QuantumCircuit, transpile

# Initialize the provider
provider = PlanqkQuantumProvider()

# Select a backend
backend = provider.get_backend("azure.ionq.simulator")

# Create a qiskit circuit
circuit = QuantumCircuit(3, 3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure(range(3), range(3))

# Transpile the circuit for the selected backend
circuit = transpile(circuit, backend)

# Execute the circuit on the selected backend
job = backend.run(circuit, shots=100)

# Monitor job status and get results
print(f"Status: {job.status()}")
print(f"Result: {job.result()}")

NOTE

Executing your quantum circuits or programs on the PlanQK platform may lead to execution costs depending on selected backend and number of shots. Please find an overview about the costs for each backend on our pricing page.

Retrieving Quantum Jobs

Due to queuing at the quantum provider, job execution may take hours or even days. To retrieve your job later, you can use the retrieve_job function provided by the backend:

# Submit the quantum circuit to the backend
job = backend.run(circuit, shots=10)

# Get the job ID for future reference
print("Job ID:", job.id)
# Example Output: Job ID: 6ac422ad-c854-4af4-b37a-efabb159d92e
...
# Get the backend 
backend = provider.get_backend("azure.ionq.simulator")
# Retrieve the job through its ID
job = backend.retrieve_job("6ac422ad-c854-4af4-b37a-efabb159d92e")

You can also get an overview of all your jobs by executing provider.jobs() or by visiting the Quantum Jobs page.

Working with the QuEra Aquila Braket Device

To execute a task on the QuEra Aquila device, you'll create an Analog Hamiltonian Simulation (AHS) program and discretize it according to the device specifications. Here's a concise example:

from planqk import PlanqkQuantumProvider
from braket.ahs.atom_arrangement import AtomArrangement
from braket.ahs.analog_hamiltonian_simulation import AnalogHamiltonianSimulation
from braket.timings.time_series import TimeSeries
from braket.ahs.driving_field import DrivingField

# Instantiate the PlanQK provider and select the QuEra Aquila backend
provider = PlanqkQuantumProvider()
backend = provider.get_backend("aws.quera.aquila")

# Define a simple atom arrangement
atom_array = AtomArrangement().add((0, 0)).add((4, 0))  # Two atoms at (0, 0) and (4, 0)

# Define driving fields
rabi_frequency = TimeSeries().linspace(0, 1, 100)  # Rabi frequency ramp
driving_field = DrivingField(rabi_frequency=rabi_frequency)

# Create the AHS program
ahs_program = AnalogHamiltonianSimulation(register=atom_array, hamiltonian=driving_field)

# Discretize the AHS program according to the device's specifications
discretized_program = ahs_program.discretize(backend.properties)

# Execute the discretized AHS program on the selected backend
task = backend.run(discretized_program)

# Monitor task status and get results
result = task.result()
post_sequences = [list(measurement.post_sequence) for measurement in result.measurements]
post_sequences = ["".join(['1' if site == 0 else '0' for site in post_sequence]) for post_sequence in post_sequences]
counters = {}
for post_sequence in post_sequences:
    if post_sequence in counters:
        counters[post_sequence] += 1
    else:
        counters[post_sequence] = 1

print(f"Status: {task.state()}, Result: {counters}")

Retrieving Braket Tasks

To retrieve a task you ran earlier, note down its ID and create a PlanqkAwsQuantumTask object by providing the ID:

# Submit the program to the backend
task = backend.run(discretized_program)

# Get the task ID for future reference
print("Task ID:", task.id)
# Example Output: Task ID: 6ac422ad-c854-4af4-b37a-efabb159d92e

# Retrieve the task using its ID
task = PlanqkAwsQuantumTask("6ac422ad-c854-4af4-b37a-efabb159d92e")

You can also get an overview of your tasks by either executing provider.jobs() or by visiting the Quantum Jobs page. Note that your tasks are referred to as “jobs” on this page.

Deploy your Qiskit circuit as a PlanQK Service

To deploy your circuit to the PlanQK Platform you may adapt the program.py file of the python-starter template.

NOTE

To create a new Qiskit development project, you may run planqk init and select Starter Qiskit as coding template. Further instructions are available here.

The program.py file contains a run() method which is called when the service is executed. Copy and paste the code from above into the run() method and add the following line at the end of the function:

return ResultResponse(result={"status": "COMPLETED"})

You may want to add some additional information to the ResultResponse object, e.g., the actual results of your circuit. You are now able to deploy your circuit as a PlanQK Service.

Use planqk up to deploy your service to the PlanQK Platform. Next, you may use planqk run to execute your service.

What's next?

• See our supported quantum backends and simulators.
• Check out this Jupyter notebook showing how to utilize the PlanQK Quantum SDK.