Skip to content

hybrid-computing-interactive.md

Latest commit

 

History

History
240 lines (170 loc) · 12.6 KB

hybrid-computing-interactive.md

File metadata and controls

240 lines (170 loc) · 12.6 KB
author azure-quantum-content
description Understand the architecture of sessions in hybrid quantum computing and learn how to create a new session.
ms.date 02/24/2026
ms.author quantumdocwriters
ms.service azure-quantum
ms.subservice qdk
ms.topic how-to
no-loc
Q#
$$v
Variational Quantum Eigensolver
Quantum Approximate Optimization Algorithm
target
targets
AI
azure-quantum
Azure Quantum
Microsoft Quantum Development Kit
Circuit Editor
cirq
Cirq
CodeLens
Copilot
Google
IBM
IntelliSense
Jupyter
Jupyter Notebook
Microsoft
Microsoft's
OpenQASM
Python
Q#
QDK
QDK's
qiskit
Qiskit
SDK
Visual Studio Code
VS Code
title Get Started with Sessions
uid microsoft.quantum.hybrid.interactive

Get started with sessions

Sessions are a key feature of hybrid quantum computing that allow you to group multiple quantum computing jobs together. A session is a logical grouping of one or more jobs that you submit to a single target. Each session has a unique ID attached to each job in that session. Sessions are useful when you want to run multiple quantum computing jobs in sequence, and run classical code between quantum jobs.

This article explains the architecture of sessions in hybrid quantum computing and how to create a new session in Azure Quantum.

Prerequisites

To create a session, you need the following prerequisites:

  • An Azure account with an active subscription. If you don’t have an Azure account, then register for free and sign up for a pay-as-you-go subscription.

  • An Azure Quantum workspace. For more information, see Create an Azure Quantum workspace.

  • A Python environment with Python and Pip installed.

  • The latest version of Visual Studio Code (VS Code), with the QDK extension, Python extension, and Jupyter extension installed.

  • The qdk Python library. To submit Qiskit and Cirq programs, install the azure, qiskit, and cirq extras.

    pip install --upgrade "qdk[azure,qiskit,cirq]"

What is a session?

In sessions, you can move the client compute resource to the cloud for lower-latency and the ability to run your quantum program multiple times with different parameters. You can logically group jobs into one session, and you can prioritize jobs in that session over non-session jobs. Qubit states don't persist between jobs, but jobs in a session have shorter queue times. Shorter queue times allow you to run complex algorithms to better organize and track your individual quantum computing jobs.

Sessions are useful for parameterized quantum algorithms, where the output of one quantum computing job is used to define input parameters for the next quantum computing job. The most common examples of this type of algorithm are :::no-loc text="Variational Quantum Eigensolvers"::: (VQE) and :::no-loc text="Quantum Approximate Optimization Algorithms"::: (QAOA).

Supported hardware

Sessions are supported on all quantum computing hardware providers. In some cases, jobs that are submitted within a session are prioritized in the queue of that target. For more information, see Target behavior.

How to create a session

To create a session, follow these steps:

Q# + Python

This example shows how to create a session with Q# inline code in a Jupyter notebook in VS Code.

Note

Sessions are managed with Python, even when running Q# inline code.

  1. In VS Code, open the View menu and choose Command Palette.

  2. Enter and select Create: New Jupyter Notebook.

  3. In the top-right, VS Code will detect and display the version of Python and the virtual Python environment that was selected for the notebook. If you have multiple Python environments, you may need to select a kernel using the kernel picker in the top right. If no environment was detected, see Jupyter Notebooks in VS Code for setup information.

  4. In the first cell of the notebook, run the following code:

    from qdk.azure import Workspace

workspace = Workspace(resource_id="") # add your resource ID

  5. Add a new cell in the notebook and import the qsharp Python package:

    from qdk import qsharp

  6. Choose your quantum target. In this example, the target is the IonQ simulator.

    target = workspace.get_targets("ionq.simulator")

  7. Select the configurations of the target profile, either Base, Adaptive_RI, or Unrestricted.

    qsharp.init(target_profile=qsharp.TargetProfile.Base)

    [!NOTE] Adaptive_RI target profile jobs are currently supported on Quantinuum targets. For more information, see Integrated hybrid quantum computing.

  8. Write your Q# program. For example, the following Q# program generates a random bit. To illustrate the use of input arguments, this program takes an integer, n, and an array of angles, angle, as input.

    %%qsharp
import Std.Measurement.*;
import Std.Arrays.*;

operation GenerateRandomBits(n: Int, angle: Double[]) : Result[] {
   use qubits = Qubit[n]; // n parameter as the size of the qubit array
   for q in qubits {
       H(q);
   }
   R(PauliZ, angle[0], qubits[0]); // arrays as entry-points parameters
   R(PauliZ, angle[1], qubits[1]);
   let results = MeasureEachZ(qubits);
   ResetAll(qubits);
   return results;
}

  9. Next, you create a session. Let's say you want to run GenerateRandomBit operation three times, so you use target.submit to submit the Q# operation with the target data and you repeat the code three times - in a real world scenario, you may want to submit different programs instead of the same code.

    angle = [0.0, 0.0]
with target.open_session(name="Q# session of three jobs") as session:
    target.submit(input_data=qsharp.compile(f"GenerateRandomBits(2, {angle})"), name="Job 1", shots=100) # First job submission
    angle[0] += 1
    target.submit(input_data=qsharp.compile(f"GenerateRandomBits(2, {angle})"), name="Job 2", shots=100) # Second job submission
    angle[1] += 1
    target.submit(input_data=qsharp.compile(f"GenerateRandomBits(2, {angle})"), name="Job 3", shots=100) # Third job submission

session_jobs = session.list_jobs()
[session_job.details.name for session_job in session_jobs]

    [!IMPORTANT] When you pass arguments as parameters to the job, the arguments are formatted into the Q# expression when qsharp.compile is called. This means that you need to format your arguments as Q# objects. In this example, because arrays in Python are already printed as [item0, item1, ...], the input arguments match the Q# formatting. For other Python data structures, you might need more handling to get the string values inserted into the Q# in a compatible way.

  10. Once you create a session, you can use workspace.list_session_jobs to retrieve a list of all jobs in the session. For more information, see How to manage sessions.

Qiskit

  1. Import additional modules from azure-quantum and qiskit.

    from qdk.qiskit import QuantumCircuit
from qdk.azure import Workspace
from azure.quantum.qiskit import AzureQuantumProvider

  2. Create a provider object with your Quantum workspace information.

    workspace = Workspace(resource_id = "") # add your resource ID

provider = AzureQuantumProvider(workspace)

  3. Write your quantum circuit. For example, the following circuit generates a random bit.

    circuit = QuantumCircuit(2, 2)
circuit.name = "GenerateRandomBit"
circuit.h(0)
circuit.cx(0,1)
circuit.measure([0,1], [0,1])
circuit.draw()

  4. Create a backend instance with the quantum target of your choice. In this example, set your target to the IonQ simulator.

    backend = provider.get_backend("ionq.simulator")

  5. Create a session. Let's say that you want to run your quantum circuit three times, so you use backend.run to submit the Qiskit circuit, and you repeat the code three times. In a real world scenario, you might want to submit different programs instead of the same code. You can use workspace.list_session_jobs to retrieve a list of all jobs in the session. For more information, see How to manage sessions.

    with backend.open_session(name="Qiskit Session") as session:
    job1 = backend.run(circuit=circuit, shots=100, job_name="Job 1") # First job submission
    job1.wait_for_final_state()
    job2 = backend.run(circuit=circuit, shots=100, job_name="Job 2") # Second job submission
    job2.wait_for_final_state()
    job3 = backend.run(circuit=circuit, shots=100, job_name="Job 3") # Third job submission
    job3.wait_for_final_state()

session_jobs = session.list_jobs()
[session_job.details.name for session_job in session_jobs]

Cirq

  1. Write your quantum circuit. For example, the following circuit generates a random bit.

    from cirq import LineQubit, Circuit, H, CNOT, measure

q0 = LineQubit(0)
q1 = LineQubit(1)
circuit = Circuit(
    H(q0),
    CNOT(q0, q1),
    measure(q0, key='q0'),
    measure(q1, key='q1')
)

print(circuit)

  2. Create a service object with your Quantum workspace information.

    from qdk.azure.cirq import AzureQuantumService

service = AzureQuantumService(resource_id = "") # add your resource ID

  3. Choose your quantum target. In this example, the target is the IonQ simulator.

    [!NOTE] Cirq circuits can use only IonQ or Quantinuum targets.

    target = service.get_target("ionq.simulator")

  4. Create a session. Let's say that you want to run your quantum circuit three times, so you use target.submit to submit the Cirq circuit, and you repeat the code three times. In a real world scenario, you might want to submit different programs instead of the same code. You can use workspace.list_session_jobs to retrieve a list of all jobs in the session. For more information, see How to manage sessions.

    with target.open_session(name="Cirq Session") as session:
    target.submit(program=circuit, name="Job 1", repetitions=100) # First job submission
    target.submit(program=circuit, name="Job 2", repetitions=100) # Second job submission
    target.submit(program=circuit, name="Job 3", repetitions=100) # Third job submission

session_jobs = session.list_jobs()
[session_job.details.name for session_job in session_jobs]

Target behavior

Each quantum hardware provider defines their own heuristics to best manage the prioritization of jobs within a session.

Quantinuum

If you choose to submit jobs within a session to a Quantinuum target, then your session has exclusive access to the hardware as long as you queue jobs within one minute of each other. After that, your jobs are accepted and handled with the standard queueing and prioritization logic.

Related content

  • How to manage your sessions
  • Run hybrid quantum computing