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

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">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
        <ExecutionTarget>ionq.qpu</ExecutionTarget>
      </PropertyGroup>
    </Project>
    
  8. 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 Azure CLI

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

  1. From the Visual Studio Code menu, select Terminal > New Terminal.

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

    az login
    
  3. 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 the Azure portal.

    az account set -s MySubscriptionID
    
  4. 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
    
    

    Note

    The MyLocation parameter in the example above is the Region specified on the Create Quantum Workspace page when following the steps in Create an Azure Quantum workspace. Region and Location are synonymous. The parameter value may be expressed in mixed case surrounded by quotes, for example, -l "West US 2", or in lower case with no spaces or quotes, such as -l westus2.

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

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 provides design-time feedback on the compatibility of your program for Quantinuum's hardware.

    <Project Sdk="Microsoft.Quantum.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
        <ExecutionTarget>quantinuum.hqs-lt</ExecutionTarget>
      </PropertyGroup>
    </Project>
    
  8. 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 Azure CLI

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

  1. From the Visual Studio Code menu, select Terminal > New Terminal.

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

    az login
    
  3. 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 the Azure portal.

    az account set -s MySubscriptionID
    
  4. 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
    
    

    Note

    The MyLocation parameter in the example above is the Region specified on the Create Quantum Workspace page when following the steps in Create an Azure Quantum workspace. Region and Location are synonymous. The parameter value may be expressed in mixed case surrounded by quotes, for example, -l "West US 2", or in lower case with no spaces or quotes, such as -l westus2.

  5. 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
    ----------  ----------------------------------------------  --------------------  --------------------
    quantinuum  quantinuum.hqs-lt                           Available             0
    quantinuum  quantinuum.hqs-lt-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'll see:

az quantum job submit --target-id quantinuum.hqs-lt -o table
 Name        ID                                    Status    Target                Submission time
 ----------  ------------------------------------  --------  --------              ---------------------------------
 QuantumRNG  b4d17c63-2119-4d92-91d9-c18d1a07e08f  Waiting   quantinuum.hqs-lt  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   quantinuum.hqs-lt  2020-10-22T22:41:27.8855301+00:00

Status in the above table changes 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 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 dictate the types of Q# programs you can 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 Q# programming language user guide.