Submit quantum jobs to Azure Quantum

Article
03/03/2023

In this article you will find the steps for how to submit quantum computing jobs to Azure Quantum using the Azure portal, Python, Jupyter Notebooks, or the Azure CLI.

Note

The examples in this topic use the Microsoft Quantum Development Kit (Classic QDK) and are not yet compatible with the Azure Quantum Development Kit Preview (Modern QDK). For more information about the Modern QDK, see the QSharp GitHub Wiki.

Prerequisites

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.

Create a new Notebook in your workspace

Log in to the Azure portal and select a workspace.
In the left blade, select Notebooks.
Click My Notebooks and click Add New.
In Kernel Type, select IQ#.
Type a name for the file, for example submit-quantum-job.ipynb, and click Create file.

Note

You can also upload a Notebook to your Azure Quantum workspace. For more information, see Upload notebooks.

When your new Notebook opens, it automatically creates the code for the first cell - a connection command based on your subscription and workspace information.

Note

Unless otherwise noted, you should run each cell in order as you create it to avoid any compilation issues.

Click the triangular "play" icon to the left of the cell to run the code. The program authenticates to your Azure account and displays the targets available in your workspace.

Write a Q# operation

Select + Code to add a new cell and enter and run your Q# code. This example uses a GenerateRandomBit operation.

operation GenerateRandomBit() : Result {
    use q = Qubit();
    H(q);
    let r = M(q);
    Reset(q);
    return r;
}

Connect to a quantum target

Add a new cell and use the %azure.target magic command to set the active target. Any of the targets listed previously can be used, but note that costs may be incurred for some. For more information about job costs, see Azure Quantum job costs.

For this example, use the free ionq.simulator.

%azure.target ionq.simulator

Submit your job

To submit your job, run the %azure.execute magic command with the Q# operation you defined earlier.

%azure.execute GenerateRandomBit

After submitting a job, you can check its status with the command %azure.status <job ID> or view its results with the command %azure.output. You can view a list of all your jobs with the command %azure.jobs.

Some helpful tips while using Q# Jupyter Notebooks:

Use the command %lsmagic to see all of the available magic commands, including the ones for Azure Quantum.
Detailed usage information for any magic command can be displayed by simply appending a ? to the command, for example, %azure.connect?.
Documentation for magic commands is also available online: %azure.connect, %azure.target, %azure.submit, %azure.execute, %azure.status, %azure.output, %azure.jobs

Prerequisites

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.
The latest version of the Quantum Development Kit for Python. This installs the qsharp Python package and the IQ# kernel, which powers the Q# Jupyter Notebook and Python experiences.

Note

When installing Python, the option to Install using conda is recommended. The steps in this article assume a conda installation.

Quantum computing with Q# and Python

The Python environment in the conda environment that you created earlier already includes the qsharp Python package. Make sure you are running your Python script from a terminal where this conda environment is activated.
Write your Q# operations in a *.qs file. When running import qsharp in Python, the IQ# kernel automatically detects any .qs files in the same folder, compiles them, and reports any errors. If compilation is successful, the compiled Q# operations will become available for use directly from within Python.
- For example, the contents of your .qs file could look something like this:
```
namespace Test {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;

    operation GenerateRandomBits(n : Int) : Result[] {
        use qubits = Qubit[n];
        ApplyToEach(H, qubits);
        return MultiM(qubits);
    }
}
```
Create a Python script in the same folder as your *.qs file. Azure Quantum functionality is available by running import qsharp.azure and then calling the Python commands to interact with Azure Quantum. For reference, see the complete list of qsharp.azure Python commands. You'll need the resource ID of your Azure Quantum workspace in order to connect. (The resource ID can be found on your workspace page in the Azure portal.)

If your workspace was created in an Azure region other than "West US", you also need to specify the region as the location parameter to qsharp.azure.connect().

For example, your Python script could look like this:
```
import qsharp
import qsharp.azure
from Test import GenerateRandomBits

qsharp.azure.connect(
   resourceId="/subscriptions/.../Microsoft.Quantum/Workspaces/WORKSPACE_NAME",
   location="West US")
qsharp.azure.target("ionq.simulator")
result = qsharp.azure.execute(GenerateRandomBits, n=3, shots=1000, jobName="Generate three random bits")
print(result)
```
where GenerateRandomBits is the Q# operation in a namespace Test that is defined in your *.qs file, n=3 is the parameter to be passed to that operation, shots=1000 (optional) specifies the number of repetitions to perform, and jobName="Generate three random bits" (optional) is a custom job name to identify the job in the Azure Quantum workspace.
Run your Python script by running the command python test.py, where test.py is the name of your Python file. If successful, you should see your job results displayed to the terminal. For example:
```
{'[0,0,0]': 0.125, '[1,0,0]': 0.125, '[0,1,0]': 0.125, '[1,1,0]': 0.125, '[0,0,1]': 0.125, '[1,0,1]': 0.125, '[0,1,1]': 0.125, '[1,1,1]': 0.125}
```

To view the details of all jobs in your Azure Quantum workspace, run the command qsharp.azure.jobs():

>>> qsharp.azure.jobs()
[{'id': 'f4781db6-c41b-4402-8d7c-5cfce7f3cde4', 'name': 'GenerateRandomNumber 3 qubits', 'status': 'Succeeded', 'provider': 'ionq', 'target': 'ionq.simulator', 'creation_time': '2020-07-17T21:45:43.4405253Z', 'begin_execution_time': '2020-07-17T21:45:54.09Z', 'end_execution_time': '2020-07-17T21:45:54.101Z'}, {'id': '1b03cc74-b5d5-4ffa-81db-465f08ae6cd0', 'name': 'GenerateRandomBit', 'status': 'Succeeded', 'provider': 'ionq', 'target': 'ionq.simulator', 'creation_time': '2020-07-21T19:44:17.1065156Z', 'begin_execution_time': '2020-07-21T19:44:25.85Z', 'end_execution_time': '2020-07-21T19:44:25.858Z'}]

To view the detailed status of a particular job, pass the job ID to qsharp.azure.status() or qsharp.azure.output(), for example:

>>> qsharp.azure.status('1b03cc74-b5d5-4ffa-81db-465f08ae6cd0')
{'id': '1b03cc74-b5d5-4ffa-81db-465f08ae6cd0', 'name': 'GenerateRandomBit', 'status': 'Succeeded', 'provider': 'ionq', 'target': 'ionq.simulator', 
'creation_time': '2020-07-21T19:44:17.1065156Z', 'begin_execution_time': '2020-07-21T19:44:25.85Z', 'end_execution_time': '2020-07-21T19:44:25.858Z'}

>>> qsharp.azure.output('1b03cc74-b5d5-4ffa-81db-465f08ae6cd0')
{'0': 0.5, '1': 0.5}

Prerequisites

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.
The latest version of the Quantum Development Kit for Jupyter Notebooks. This installs Jupyter Notebook and the IQ# kernel, which powers the Q# Jupyter Notebook and Python experiences.

Quantum computing with Q# Jupyter Notebooks

Run jupyter notebook from the terminal where your conda environment is activated. This starts the notebook server and opens Jupyter in a browser.
Create your Q# notebook (via New → Q#) and write your Q# program.
Write your Q# operations directly in the notebook. Running the cells will compile the Q# code and report whether there are any errors.
- For example, you could write a Q# operation that looks like this:
```
operation GenerateRandomBit() : Result {
    use q = Qubit();
    H(q);
    let r = M(q);
    Reset(q);
    return r;
}
```
Once you have your Q# operations defined, use the %azure.* magic commands to connect and submit jobs to Azure Quantum. You'll use the resource ID of your Azure Quantum workspace in order to connect. (The resource ID can be found on your workspace page in the Azure portal.)

If your workspace was created in an Azure region other than "West US", you also need to specify this as the location parameter to %azure.connect.
- For example, the following commands will connect to an Azure Quantum workspace and run an operation on the ionq.simulator target:
```
%azure.connect "/subscriptions/.../Microsoft.Quantum/Workspaces/WORKSPACE_NAME" location="West US"

%azure.target ionq.simulator

%azure.execute GenerateRandomBit
```
  where GenerateRandomBit is the Q# operation that you have already defined in the notebook.
After submitting a job, you can check its status with the command %azure.status or view its results with the command %azure.output. You can view a list of all your jobs with the command %azure.jobs.

Some helpful tips while using Q# Jupyter Notebooks:

Use the command %lsmagic to see all of the available magic commands, including the ones for Azure Quantum.
Detailed usage information for any magic command can be displayed by simply appending a ? to the command, for example, %azure.connect?.
Documentation for magic commands is also available online: %azure.connect, %azure.target, %azure.submit, %azure.execute, %azure.status, %azure.output, %azure.jobs

Prerequisites

Ensure that the following items are installed on your computer:

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.
The latest version of the Quantum Development Kit.
The Azure CLI and the quantum CLI extension.

Submit a job to Azure Quantum with the Azure CLI

These steps show how to use the Azure CLI to run a quantum application and select a target from the different providers of your Azure Quantum workspace.

Tip

With the Azure Quantum extension for Visual Studio Code installed, you have full Azure CLI functionality from a terminal window within VS Code.

You will also find a full reference for all commands and features available through the az quantum extension in the corresponding section of the Azure CLI documentation.

Note

A provider is a partner quantum service consisting of quantum hardware, a simulator, or an optimization service.

Log in to Azure using your credentials. You'll get a list of subscriptions associated with your account.
```
az login
```
Specify the subscription you want to use from those associated with your Azure account. You can also find your subscription ID in the overview of your workspace in Azure portal.
```
az account set -s <Your subscription ID>
```
You can see all the Azure Quantum workspaces in your subscription with the following command:
```
az quantum workspace list
```

You can use quantum workspace set to select a default workspace that you want to use to list and submit jobs. Note that you also need to specify the resource group and the location:

az quantum workspace set -g MyResourceGroup -w MyWorkspace -l MyLocation -o table


Location     Name                               ResourceGroup
-----------  ---------------------------------  --------------------------------
MyLocation       ws-yyyyyy                          rg-yyyyyyyyy

Tip

You can check the current workspace with the command az quantum workspace show -o table.

In your Azure Quantum workspace, there are different targets available from the providers that you added when you created the workspace. You can display a list of all the available targets with the command az quantum target list -o table:

az quantum target list -o table

  Provider      Target-id                                            Current Availability    Average Queue Time (seconds)
 ------------  ---------------------------------------------------  ----------------------  ------------------------------
 ionq          ionq.qpu                                             Available               510467
 ionq          ionq.qpu.aria-1                                      Available               176345
 ionq          ionq.simulator                                       Available               2
 microsoft-qc  microsoft.estimator                                  Available               0
 quantinuum    quantinuum.hqs-lt-s1                                 Degraded                0
 quantinuum    quantinuum.hqs-lt-s1-apival                          Available               5
 quantinuum    quantinuum.hqs-lt-s2                                 Unavailable             0
 quantinuum    quantinuum.hqs-lt-s2-apival                          Available               3
 quantinuum    quantinuum.hqs-lt-s1-sim                             Available               431
 quantinuum    quantinuum.hqs-lt-s2-sim                             Available               74
 quantinuum    quantinuum.hqs-lt                                    Degraded                0
 quantinuum    quantinuum.qpu.h1-1                                  Degraded                0
 quantinuum    quantinuum.sim.h1-1sc                                Available               5
 quantinuum    quantinuum.qpu.h1-2                                  Unavailable             0
 quantinuum    quantinuum.sim.h1-2sc                                Available               3
 quantinuum    quantinuum.sim.h1-1e                                 Available               431
 quantinuum    quantinuum.sim.h1-2e                                 Available               74
 rigetti       rigetti.sim.qvm                                      Available               5
 rigetti       rigetti.qpu.aspen-11                                 Unavailable             0
 rigetti       rigetti.qpu.aspen-m-2                                Available               5
 rigetti       rigetti.qpu.aspen-m-3                                Available               5
 Microsoft     microsoft.paralleltempering-parameterfree.cpu        Available               0
 Microsoft     microsoft.paralleltempering.cpu                      Available               0
 Microsoft     microsoft.simulatedannealing-parameterfree.cpu       Available               0
 Microsoft     microsoft.simulatedannealing.cpu                     Available               0
 Microsoft     microsoft.tabu-parameterfree.cpu                     Available               0
 Microsoft     microsoft.tabu.cpu                                   Available               0
 Microsoft     microsoft.qmc.cpu                                    Available               0
 Microsoft     microsoft.populationannealing.cpu                    Available               0
 Microsoft     microsoft.populationannealing-parameterfree.cpu      Available               0
 Microsoft     microsoft.substochasticmontecarlo.cpu                Available               0
 Microsoft     microsoft.substochasticmontecarlo-parameterfree.cpu  Available               0

To submit a new job, navigate to the directory containing your project using the command line and submit your job. Use the command az quantum job submit. You need to specify the target where you want to run your job, for example:

az quantum job submit --target-id MyProvider.MyTarget

Id                                    State    Target               Submission time
------------------------------------  -------  -------------------  ---------------------------------
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy  Waiting  MyProvider.MyTarget  2020-06-12T14:20:18.6109317+00:00

The console will output the job information, including the job ID.

You can use the job ID to track its status:

az quantum job show --job-id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table

Id                                    State      Target               Submission time
------------------------------------  ---------  -------------------  ---------------------------------
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy  Succeeded  MyProvider.MyTarget  2020-06-12T14:20:19.819981+00:00

Tip

To see all the jobs in the workspace, use the command az quantum job list -o table.

Once the job finishes, display the job's results with the command az quantum job output:

 az quantum job output --job-id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table

 Result    Frequency
 --------  -----------  -------------------------
 [0,0]     0.00000000                           |
 [1,0]     0.50000000   ▐███████████            |
 [0,1]     0.25000000   ▐█████                  |
 [1,1]     0.25000000   ▐█████                  |

Tip

To submit a job synchronously, for example, waiting for the job to complete and showing results, use the command az quantum execute --target-id MyProvider.MyTarget.

Example

Write your quantum application

First, you need the Q# quantum application that you want to run in Azure Quantum.

Tip

If this is your first time creating Q# quantum applications, see our Learn module.

In this case, we will use a simple quantum random bit generator. Create a Q# project and substitute the content of Program.qs with the following code:

namespace RandomBit {

    open Microsoft.Quantum.Canon;
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;

    @EntryPoint()
    operation GenerateRandomBit() : Result {
        use q = Qubit();
        H(q);
        return MResetZ(q);
    }
}

Note that the @EntryPoint attribute tells Q# which operation to run when the program starts.

Submit the job

In this example, we are going to use IonQ as the provider and the ionq.simulator as the target. To submit the job to the currently selected default workspace, use the command az quantum job submit:

Important

Verify that the Quantum SDK version of the *.csproj file is 0.11.2006.403 or higher. If not, it could cause a compilation error.

az quantum job submit --target-id ionq.simulator --job-name ExampleJob -o table

Name   Id                                    Status    Target          Submission time
-----  ------------------------------------  --------  --------------  ---------------------------------
ExampleJob   yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy  Waiting   ionq.simulator  2020-06-17T17:07:07.3484901+00:00

Once the job completes (that is, when it's in a Successful state), use the command az quantum job output to view the results:

az quantum job output --job-id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table

Result    Frequency
--------  -----------  -------------------------
[0,0]     0.50000000   ▐███████████            |
[0,1]     0.50000000   ▐███████████            |

The output displays a histogram with the frequency that a specific result was measured. In the example above, the result [0,1] was observed 50% of the times.

Optionally, you can use the command az quantum execute as a shortcut for both submitting and returning the results of a run.

az quantum execute --target-id ionq.simulator --job-name ExampleJob2 -o table

Result    Frequency
--------  -----------  -------------------------
[0,0]     0.50000000   ▐███████████            |
[0,1]     0.50000000   ▐███████████            |

Note that the IonQ simulator gives the probabilities of obtaining each output if we run the algorithm an infinite number of times. In this case, we see that each state has a 50% probability of being measured.

Tip

You can also check the status of your jobs from your Azure portal.

Submit quantum jobs to Azure Quantum

Prerequisites

Create a new Notebook in your workspace

Write a Q# operation

Connect to a quantum target

Submit your job

Prerequisites

Quantum computing with Q# and Python

Prerequisites

Quantum computing with Q# Jupyter Notebooks

Prerequisites

Submit a job to Azure Quantum with the Azure CLI

Example

Write your quantum application

Submit the job

Next steps

Feedback

Additional resources

Additional resources