Quickstart: Create a quantum-based random number generator in Azure Quantum

Learn how to use Azure Quantum to create a simple quantum-based random number generator.

Prerequisites

  • To complete this tutorial you need an Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
  • In this guide we'll use Visual Studio Code which you can download and use for free.

Install the Quantum Development Kit and other resources

Before you can write a Q# program and run it with one of the quantum computing providers, you'll need to install few resources:

  1. Install the Microsoft QDK for VS Code extension.

  2. Install the Azure CLI.

  3. Install the quantum CLI extension for the Azure CLI.

    az extension add -n quantum
    

Create an Azure Quantum workspace

You use the Azure Quantum service by adding an Azure Quantum workspace resource to your Azure subscription in the Azure portal. An Azure Quantum workspace resource, or workspace for short, is a collection of assets associated with running quantum or optimization applications.

To open the Azure Portal, go to https://portal.azure.com and then follow these steps:

  1. Click Create a resource and then search for Azure Quantum. On the results page, you should see a tile for the Azure Quantum (preview) service.

    Tile for the Azure Quantum (preview)
service

  2. Click Azure Quantum (preview) and then click Create. This opens a form to create a workspace.

    Create resource for the Azure Quantum (preview)
service

  3. Fill out the details of your workspace:

    • Subscription: The subscription that you want to associate with this workspace.
    • Resource group: The resource group that you want to assign this workspace to.
    • Name: The name of your workspace.
    • Region: The region for the workspace.
    • Storage Account: The Azure storage account to store your jobs and results. If you don't have an existing storage account, click Create a new storage account and complete the necessary fields. For this preview, we recommend using the default values.

    Properties for the Azure Quantum workspace

    Note

    You must be an Owner of the selected resource group to create a new storage account. For more information about how resource groups work in Azure, see Control and organize Azure resources with Azure Resource Manager.

  4. After completing the information, click the Providers tab to add providers to your workspace. A provider gives you access to a quantum service, which can be quantum hardware, a quantum simulator, or an optimization service.

    Providers for Azure Quantum

    Note

    By default, the Azure Quantum service adds the Microsoft QIO provider to every workspace.

  5. Add at least the IonQ provider, then click Review + create.

  6. Review the settings and approve the Terms and Conditions of Use of the selected providers. If everything is correct, click Create to create your workspace.

    Review and create the workspace

Note

Pricing for Azure Quantum varies by provider. Please consult the information in the Providers tab of your Azure Quantum workspace in the Azure portal for the most up-to-date pricing information.

Create a Q# project in Visual Studio Code

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

  2. Type Q#: Create New Project.

  3. Select Standalone console application.

  4. Select a directory to hold your project, such as your home directory. Enter QuantumRNG as the project name, then select Create Project.

  5. From the window that appears at the bottom, select Open new project.

  6. You should see two files: the project file and Program.qs, which contains starter code. Open Program.qs.

  7. Start by opening the QuantumRNG.csproj file and adding the ExecutionTarget property, which will give you design-time feedback on the compatibility of your program for IonQ's hardware.

<Project Sdk="Microsoft.Quantum.Sdk/0.17.2105143879">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ExecutionTarget>ionq.qpu</ExecutionTarget>
  </PropertyGroup>
</Project>
  1. Replace the contents of Program.qs with the program:
namespace QuantumRNG {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;

    @EntryPoint()
    operation GenerateRandomBits() : Result[] {
        use qubits = Qubit[4];
        ApplyToEach(H, qubits);
        return MultiM(qubits);
    }
}

Note

If you would like to learn more about this program code, see Create your first Q# program by using the Quantum Development Kit.

Prepare the AZ CLI

Next, we'll prepare your environment to run the program against the workspace you created.

  1. Log in to Azure using your credentials. You'll get a list of subscriptions associated with your account.

    az login
    
  2. 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>
    
  3. Use quantum workspace set to select the workspace you created above as the default Workspace. Note that you also need to specify the resource group and the location you created it in:

    az quantum workspace set -g MyResourceGroup -w MyWorkspace -l MyLocation -o table
    
     Location    Name         ProvisioningState    ResourceGroup    StorageAccount      Usable
     ----------  -----------  -------------------  ---------------  ------------------  --------
     MyLocation  MyWorkspace  Succeeded            MyResourceGroup  /subscriptions/...  Yes
    
    
  4. In your 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
    

    Depending on the provider you selected, you will see:

     Provider    Target-id                                       Status     Average Queue Time
     ----------  ----------------------------------------------  ---------  --------------------
     ionq        ionq.qpu                                        Available  0
     ionq        ionq.simulator                                  Available  0
    

    Note

    When you submit a job in Azure Quantum it will wait in a queue until the provider is ready to run your program. The Average Queue Time column of the target list command shows you how many seconds recently run jobs waited in the queue. This can give you an idea of how long you might have to wait.

Simulate the program in the IonQ provider

Before you run a program against real hardware, we recommend simulating it first (if possible, based on the number of qubits required) to help ensure that your algorithm is doing what you want. Fortunately, IonQ provides an idealized simulator that you can use.

Note

You can also simulate Q# programs locally using the Full State Simulator.

Run your program with az quantum execute --target-id ionq.simulator -o table. This command will compile your program, submit it to Azure Quantum, and wait until IonQ has finished simulating the program. Once it's done it will output a histogram which should look like the one below:

az quantum execute --target-id ionq.simulator -o table
Result     Frequency
---------  -----------  -------------------------
[0,0,0,0]  0.06250000   ▐█                      |
[1,0,0,0]  0.06250000   ▐█                      |
[0,1,0,0]  0.06250000   ▐█                      |
[1,1,0,0]  0.06250000   ▐█                      |
[0,0,1,0]  0.06250000   ▐█                      |
[1,0,1,0]  0.06250000   ▐█                      |
[0,1,1,0]  0.06250000   ▐█                      |
[1,1,1,0]  0.06250000   ▐█                      |
[0,0,0,1]  0.06250000   ▐█                      |
[1,0,0,1]  0.06250000   ▐█                      |
[0,1,0,1]  0.06250000   ▐█                      |
[1,1,0,1]  0.06250000   ▐█                      |
[0,0,1,1]  0.06250000   ▐█                      |
[1,0,1,1]  0.06250000   ▐█                      |
[0,1,1,1]  0.06250000   ▐█                      |
[1,1,1,1]  0.06250000   ▐█                      |

This shows an equal frequency for each of the 16 possible states for measuring 4 qubits, which is what we expect from an idealized simulator! This means we're ready to run it on the QPU.

Run the program on hardware

To run the program on hardware, we'll use the asynchronous job submission command az quantum job submit. Like the execute command this will compile and submit your program, but it won't wait until the execution is complete. We recommend this pattern for running against hardware, because you may need to wait a while for your job to finish. To get an idea of how long that may be, you can run az quantum target list -o table as described above. Depending on the provider you selected, you will see:

az quantum job submit --target-id ionq.qpu -o table
 Name        Id                                    Status    Target    Submission time
 ----------  ------------------------------------  --------  --------  ---------------------------------
 QuantumRNG  5aa8ce7a-25d2-44db-bbc3-87e48a97249c  Waiting   ionq.qpu  2020-10-22T22:41:27.8855301+00:00

The tables above show that your job has been submitted and is waiting for its turn to run. To check on the status, use the az quantum job show command, being sure to replace the job-id parameter with the Id output by the previous command, for example:

 az quantum job show -o table --job-id 5aa8ce7a-25d2-44db-bbc3-87e48a97249c 
 Name        Id                                    Status    Target    Submission time
 ----------  ------------------------------------  --------  --------  ---------------------------------
 QuantumRNG  5aa8ce7a-25d2-44db-bbc3-87e48a97249c  Waiting   ionq.qpu  2020-10-22T22:41:27.8855301+00:00

Eventually, you will see the Status in the above table change to Succeeded. Once that's done you can get the results from the job by running az quantum job output:

az quantum job output -o table --job-id 5aa8ce7a-25d2-44db-bbc3-87e48a97249c 
Result     Frequency
---------  -----------  -------------------------
[0,0,0,0]  0.05200000   ▐█                      |
[1,0,0,0]  0.07200000   ▐█                      |
[0,1,0,0]  0.05000000   ▐█                      |
[1,1,0,0]  0.06800000   ▐█                      |
[0,0,1,0]  0.04600000   ▐█                      |
[1,0,1,0]  0.06000000   ▐█                      |
[0,1,1,0]  0.06400000   ▐█                      |
[1,1,1,0]  0.07600000   ▐██                     |
[0,0,0,1]  0.04800000   ▐█                      |
[1,0,0,1]  0.06200000   ▐█                      |
[0,1,0,1]  0.07400000   ▐█                      |
[1,1,0,1]  0.08000000   ▐██                     |
[0,0,1,1]  0.05800000   ▐█                      |
[1,0,1,1]  0.06800000   ▐█                      |
[0,1,1,1]  0.05200000   ▐█                      |
[1,1,1,1]  0.07000000   ▐█                      |

The histogram you receive may be slightly different than the one above, but you should find that the states generally are observed with equal frequency.

Prerequisites

  • To complete this tutorial you need an Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
  • In this guide we'll use Visual Studio Code which you can download and use for free.

Install the Quantum Development Kit and other resources

Before you can write a Q# program and run it with one of the quantum computing providers, you'll need to install few resources:

  1. Install the Microsoft QDK for VS Code extension.

  2. Install the Azure CLI.

  3. Install the quantum CLI extension for the Azure CLI.

    az extension add -n quantum
    

Create an Azure Quantum workspace

You use the Azure Quantum service by adding an Azure Quantum workspace resource to your Azure subscription in the Azure portal. An Azure Quantum workspace resource, or workspace for short, is a collection of assets associated with running quantum or optimization applications.

To open the Azure Portal, go to https://portal.azure.com and then follow these steps:

  1. Click Create a resource and then search for Azure Quantum. On the results page, you should see a tile for the Azure Quantum (preview) service.

    Tile for the Azure Quantum (preview)
service

  2. Click Azure Quantum (preview) and then click Create. This opens a form to create a workspace.

    Create resource for the Azure Quantum (preview)
service

  3. Fill out the details of your workspace:

    • Subscription: The subscription that you want to associate with this workspace.
    • Resource group: The resource group that you want to assign this workspace to.
    • Name: The name of your workspace.
    • Region: The region for the workspace.
    • Storage Account: The Azure storage account to store your jobs and results. If you don't have an existing storage account, click Create a new storage account and complete the necessary fields. For this preview, we recommend using the default values.

    Properties for the Azure Quantum workspace

    Note

    You must be an Owner of the selected resource group to create a new storage account. For more information about how resource groups work in Azure, see Control and organize Azure resources with Azure Resource Manager.

  4. After completing the information, click the Providers tab to add providers to your workspace. A provider gives you access to a quantum service, which can be quantum hardware, a quantum simulator, or an optimization service.

    Providers for Azure Quantum

    Note

    By default, the Azure Quantum service adds the Microsoft QIO provider to every workspace.

  5. Add at least the Honeywell provider, then click Review + create.

  6. Review the settings and approve the Terms and Conditions of Use of the selected providers. If everything is correct, click Create to create your workspace.

    Review and create the workspace

Note

Pricing for Azure Quantum varies by provider. Please consult the information in the Providers tab of your Azure Quantum workspace in the Azure portal for the most up-to-date pricing information.

Create a Q# project in Visual Studio Code

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

  2. Type Q#: Create New Project.

  3. Select Standalone console application.

  4. Select a directory to hold your project, such as your home directory. Enter QuantumRNG as the project name, then select Create Project.

  5. From the window that appears at the bottom, select Open new project.

  6. You should see two files: the project file and Program.qs, which contains starter code. Open Program.qs.

  7. Start by opening the QuantumRNG.csproj file and adding the ExecutionTarget property, which will give you design-time feedback on the compatibility of your program for Honeywell's hardware.

<Project Sdk="Microsoft.Quantum.Sdk/0.17.2105143879">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ExecutionTarget>honeywell.hqs-lt-1.0</ExecutionTarget>
  </PropertyGroup>
</Project>
  1. Replace the contents of Program.qs with the program:
namespace QuantumRNG {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;

    @EntryPoint()
    operation GenerateRandomBits() : Result[] {
        use qubits = Qubit[4];
        ApplyToEach(H, qubits);
        return MultiM(qubits);
    }
}

Note

If you would like to learn more about this program code, see Create your first Q# program by using the Quantum Development Kit.

Prepare the AZ CLI

Next, we'll prepare your environment to run the program against the workspace you created.

  1. Log in to Azure using your credentials. You'll get a list of subscriptions associated with your account.

    az login
    
  2. 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>
    
  3. Use quantum workspace set to select the workspace you created above as the default Workspace. Note that you also need to specify the resource group and the location you created it in:

    az quantum workspace set -g MyResourceGroup -w MyWorkspace -l MyLocation -o table
    
     Location    Name         ProvisioningState    ResourceGroup    StorageAccount      Usable
     ----------  -----------  -------------------  ---------------  ------------------  --------
     MyLocation  MyWorkspace  Succeeded            MyResourceGroup  /subscriptions/...  Yes
    
    
  4. In your 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
    

    which gives you the output

    Provider    Target-id                                       Current Availability  Average Queue Time
    ----------  ----------------------------------------------  --------------------  --------------------
    honeywell   honeywell.hqs-lt-1.0                            Available             0
    honeywell   honeywell.hqs-lt-1.0-apival                     Available             0
    

    Note

    When you submit a job in Azure Quantum it will wait in a queue until the provider is ready to run your program. The Average Queue Time column of the target list command shows you how many seconds recently run jobs waited in the queue. This can give you an idea of how long you might have to wait.

Run the program on hardware

To run the program on hardware, we'll use the asynchronous job submission command az quantum job submit. Like the execute command this will compile and submit your program, but it won't wait until the execution is complete. We recommend this pattern for running against hardware, because you may need to wait a while for your job to finish. To get an idea of how long that may be, you can run az quantum target list -o table as described above. Depending on the provider you selected, you will see:

az quantum job submit --target-id honeywell.hqs-lt-1.0 -o table
 Name        Id                                    Status    Target                Submission time
 ----------  ------------------------------------  --------  --------              ---------------------------------
 QuantumRNG  b4d17c63-2119-4d92-91d9-c18d1a07e08f  Waiting   honeywell.hqs-lt-1.0  2020-01-12T22:41:27.8855301+00:00

The tables above show that your job has been submitted and is waiting for its turn to run. To check on the status, use the az quantum job show command, being sure to replace the job-id parameter with the Id output by the previous command, for example:

 az quantum job show -o table --job-id b4d17c63-2119-4d92-91d9-c18d1a07e08f 
 Name        Id                                    Status    Target    Submission time
 ----------  ------------------------------------  --------  --------  ---------------------------------
 QuantumRNG  b4d17c63-2119-4d92-91d9-c18d1a07e08f  Waiting   honeywell.hqs-lt-1.0  2020-10-22T22:41:27.8855301+00:00

Eventually, you will see the `Status` in the above table change to `Succeeded`. Once that's done you can get the results from the job by running `az quantum job output`:

```azurecli
az quantum job output -o table --job-id b4d17c63-2119-4d92-91d9-c18d1a07e08f 
Result     Frequency
---------  -----------  -------------------------
[0,0,0,0]  0.05200000   ▐█                      |
[1,0,0,0]  0.07200000   ▐█                      |
[0,1,0,0]  0.05000000   ▐█                      |
[1,1,0,0]  0.06800000   ▐█                      |
[0,0,1,0]  0.04600000   ▐█                      |
[1,0,1,0]  0.06000000   ▐█                      |
[0,1,1,0]  0.06400000   ▐█                      |
[1,1,1,0]  0.07600000   ▐██                     |
[0,0,0,1]  0.04800000   ▐█                      |
[1,0,0,1]  0.06200000   ▐█                      |
[0,1,0,1]  0.07400000   ▐█                      |
[1,1,0,1]  0.08000000   ▐██                     |
[0,0,1,1]  0.05800000   ▐█                      |
[1,0,1,1]  0.06800000   ▐█                      |
[0,1,1,1]  0.05200000   ▐█                      |
[1,1,1,1]  0.07000000   ▐█                      |

The histogram you receive may be slightly different than the one above, but you should find that the states generally are observed with equal frequency.

Note

If you run into an error while working with Azure Quantum, you can check our list of common issues.

Next steps

This quickstart demonstrated how to get started running Q# programs against different quantum computing simulators and QPUs. For more information on the available providers, see the Quantum computing provider overview documentation.

We recommend you continue your journey by learning more about the different types of targets in Azure Quantum, which will dictate which Q# programs you may run against a given provider. You might also be interested in learning how to submit Q# jobs with Python, Jupyter Notebooks, or the Azure CLI.

Looking for more samples to run? Check out the samples directory for Azure Quantum.

Lastly, if you would like to learn more about writing Q# programs please see the Microsoft Quantum Documentation.