Interactive quantum computing: sessions

This article explains the architecture of interactive quantum computing, also known as sessions, and how to create a new session.

In this model of hybrid quantum computing, the client compute resource may be moved to the cloud, resulting in lower-latency and the ability to repeat execution of the quantum circuit with different parameters. Jobs can be grouped logically into one session, and the jobs in that session can be prioritized over non-session jobs. Although the qubit states don't persist between jobs, a session allows for shorter queue times for jobs and longer running problems.

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, 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 Azure Quantum azure-quantum package. If you want to use Qiskit or Cirq, you need to install the azure-quantum package with the [qiskit] or [cirq] tags.

  pip install --upgrade azure-quantum[qiskit] 
  

What is a session?

A session is a logical grouping of one or more jobs submitted to a single target. Each session has a unique ID attached to each job in that session.

Sessions allow you to organize multiple quantum computing jobs with the ability to run classical code between quantum jobs. You'll be able to run complex algorithms to better organize and track your individual quantum computing jobs.

A key user scenario where you may want to combine jobs in a session is parameterized quantum algorithms where the output of one quantum computing job informs the parameters of the next quantum computing job. The most common examples of this type of algorithm are Variational Quantum Eigensolvers (VQE) and Quantum Approximate Optimization Algorithms (QAOA).

Supported hardware

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

Get started with sessions

Sessions are managed with Python and can be created for any QIR quantum programs, including Q#, Qiskit, and Cirq programs.

Q# + Python

This example shows how to create a session with Q# inline code using a Jupyter Notebook in Visual Studio Code. You can also create sessions using a Python program that invokes an adjacent Q# program.

Note

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

1. In VS Code, select View > Command palette and select Create: New Jupyter Notebook.

2. 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.

3. In the first cell of the notebook, run

   import azure.quantum
   
   workspace = azure.quantum.Workspace(
       resource_id = "", # add your resource ID
       location = "", # add your location, for example "westus"
   )
   

4. Click + Code to add a new cell in the notebook and import qsharp Python SDK.

   import qsharp
   

5. Select the quantum target of your choice. In this example, you're using IonQ simulator as target.

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

6. Select the configurations of your target profile, either Base or Unrestricted.

   qsharp.init(target_profile=qsharp.TargetProfile.Base) # or qsharp.TargetProfile.Unrestricted
   

7. 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
   open Microsoft.Quantum.Measurement;
   open Microsoft.Quantum.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;
   }
   

8. 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 passing arguments as parameters to the job, they are formatted into the Q# expression when calling qsharp.compile. This means that you need to be careful 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.

9. 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. First, you need to import additional modules from azure-quantum and qiskit. Next, create a provider object with your Quantum workspace information.

   from qiskit import QuantumCircuit
   from azure.quantum import Workspace
   from azure.quantum.qiskit import AzureQuantumProvider
   
   workspace = Workspace(
               resource_id = "", # add your resource ID
               location = "") # add your location
   
   provider = AzureQuantumProvider(workspace)
   

2. 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()
   

3. Next, create a backend instance with the quantum target of your choice. In this example, set IonQ simulator as the target.

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

4. Next, create a session. Let's say 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 may 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. First, write your quantum circuit. For example, the following circuit generates a random bit.

   import cirq
   
   q0 = cirq.LineQubit(0)
   q1 = cirq.LineQubit(1)
   circuit = cirq.Circuit(
       cirq.H(q0),  # H gate
       cirq.CNOT(q0, q1),
       cirq.measure(q0, key='q0'),
       cirq.measure(q1, key='q1')
   )
   print(circuit)
   

2. Then, create a service object with your Quantum workspace information.

   from azure.quantum.cirq import AzureQuantumService
   
   service = AzureQuantumService(
               resource_id = "", # add your resource ID
               location = "") # add your location
   

3. Select the quantum target of your choice. In this example, you're using IonQ simulator as target.

   Note

   Cirq circuits can only use IonQ or Quantinuum targets.

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

4. Next, you create a session. Let's say 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 may 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]
   

Monitoring sessions

You can use the Job management blade in your Quantum workspace to view all top-level submitted items, including sessions and individual jobs that aren't associated with any session.

1. Select the Job management blade in your Quantum workspace.
2. Identify the jobs of type Session. In this view you can see the Unique ID of a Session in column Id and monitor its Status. The states of a session are:
   • Waiting: Jobs within the session are being executed.
   • Succeeded: Session has ended successfully.
   • TimeOut: If no new job is submitted within the session for 10 minutes, that session times out. For more information, see Session timeouts.
   • Failed: If a job within a session fails, that session ends and reports a status of Failed. For more information, see Job failure policy within sessions.
3. Click on a session's name for more details.
4. You can see the list of All jobs within the session and monitor their status.

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, your session will have exclusive access to the hardware as long as you queue jobs within one minute from each other. After that, your jobs will be accepted and handled with the standard queueing and prioritization logic.

Related content

• How to manage sessions
• Integrated quantum computing