Get started with Azure Quantum and IonQ

If you prefer using the Microsoft ecosystem, it’s easy to get started running quantum programs on IonQ’s trapped ion machines using Microsoft Azure Quantum. Azure Quantum uses the Q# language to represent quantum programs.

Before you begin

To use Azure Quantum, you’ll need a Microsoft Azure account and quantum development toolchain—the account and software are all free.

1. Create a free Microsoft Azure account using this guide

2. Download and install Visual Studio Code from the VSCode download page

3. Install the Microsoft Quantum Development Kit for Visual Studio Code

4. Install the Azure CLI.

5. Install the quantum CLI extension for the Azure CLI by running this Azure CLI command:

az extension add -n quantum

Provision a workspace

To use Azure Quantum, you’ll need to provision an Azure Quantum workspace.

1. Start by navigating to your Azure portal: https://portal.azure.com

2. Click Create a resource. Search for Azure Quantum. In the results, you’ll see a listing for the Azure Quantum service.

3. Click Azure Quantum and then Create. To create a workspace, you’ll need to assign the Azure subscription, resource group, name and region of your workspace. You’ll also need to select a storage account to store your Azure Quantum jobs and results. If you don’t have an existing storage account, click Create a new storage account and complete the required fields. Using the default values is fine for this guide!

   Tip: Save your Azure Subscription ID somewhere convenient — you’ll need it on the command line!

4. After filling out the workspace details form, click the Providers tab to add a provider (IonQ is an Azure Quantum provider, but Microsoft also provides access to other quantum hardware, simulators and optimization services).

5. Add the IonQ provider. Click Review + create.

6. Approve the Terms and Conditions of Use, and click Create to launch your workspace!

Write your first Q# program

Now that we’ve provisioned your workspace, you can write your first Q# program.

1. In VSCode click View > 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 with the value ionq.qpu, which will give you design-time feedback on the compatibility of your program with IonQ’s quantum hardware.

<Project Sdk="Microsoft.Quantum.Sdk/0.17.2105143879">
    <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ExecutionTarget>ionq.qpu</ExecutionTarget>
    </PropertyGroup>
</Project>

8. Replace Program.qs with this simple 2-bit random number generator:

namespace QuantumRNG {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;

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

(To learn more about Q#, we recommend starting with Microsoft’s article Create your first Q# program by using the Quantum Development Kit.)

Set up the AZ CLI

Now that we have a program, we can prepare our environment to run the program in the Azure Quantum workspace we created earlier.

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

az login

2. Select your Azure subscription:

az account set -s <Your subscription ID>

3. Use quantum workspace set to select the workspace 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. You can find all the available targets from the providers you added when you created your workspace by running this command:

az quantum target list -o table

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

5. When you submit a job in Azure Quantum it will wait in a queue until it runs on IonQ hardware. The Average Queue Time column shows you how many seconds recently run jobs waited in the queue, which should give you a rough idea of how long you’ll have to wait.

Simulate the program

Before you run a program on a real quantum computer, it’s best to simulate it first, to help ensure that your algorithm was implemented correctly. To this end, we provide an error-free simulator for programs of up to 29 qubits.

Run your program on our simulator using the command `az quantum execute --target-id ionq.simulator -o table`. This command will compile your program, submit it to Azure Quantum, and wait until we’ve finished simulation. Once it's done, you’ll receive a histogram of output states.

az quantum execute --target-id ionq.simulator -o table

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

Each of the 4 possible states for measuring 2 qubits were returned with equal frequency, which is what we expect from an error-free quantum simulator! Your program looks bug-free and ready to run on hardware.

Run the program on hardware

At last! It’s time to run your program on a real quantum computer. We'll use the asynchronous job submission command az quantum job submit. Like the execute command, this will compile and submit your program, and then return control so you don’t have to wait while your program sits in our queue. (If you don’t want to wait at all, please contact our sales team for reserved access.) To get an idea of current queue times, run az quantum target list -o table as shown above.

az quantum job submit --target-id ionq.qpu -o table

Name        Id                                    Status    Target    Submission time
----------  ------------------------------------  --------  --------  ---------------------------------
QuantumRNG  ef4d78f3-3614-433b-a67f-288c6409c81a  Waiting   ionq.qpu  2021-06-08T12:32:41.192837+00:00

Here we see that the job was successfully submitted and is queued to run. To check on its status, use the az quantum job show command, being sure to replace the job-id parameter with the Id output from the previous command:

az quantum job show -o table --job-id ef4d78f3-3614-433b-a67f-288c6409c81a

Name        Id                                    Status    Target    Submission time
----------  ------------------------------------  --------  --------  ---------------------------------
QuantumRNG  ef4d78f3-3614-433b-a67f-288c6409c81a  Waiting   ionq.qpu  2021-06-08T12:34:51.381827+00:00

Once the job has executed, you’ll see its `Status change to Succeeded. Then you can pull its results by running az quantum job output:

az quantum job output -o table --job-id ef4d78f3-3614-433b-a67f-288c6409c81a

Result  Frequency
------  -----------  -------------------------
[0,0]   0.240000000  ▐█████                  |
[1,0]   0.260000000  ▐█████                  |
[0,1]   0.230000000  ▐█████                  |
[1,1]   0.270000000  ▐█████                  |

Your results will vary slightly (it’s a random number generator after all!) but the states should be returned with more or less equal frequency.

If you run into an error while working with Azure Quantum, please see Microsoft’s list of common issues as a first step.

Additional Resources

Our best practices page provides detailed instructions for getting the most out of our trapped-ion systems, and our support center is always available to help you solve any problems you might run into.

Want to learn more about writing Q# programs? Please see the Microsoft Quantum Documentation. Want to try other libraries? See quickstarts for Amazon Braket, IBM’s Qiskit, Google’s Cirq, or ProjectQ.

Share on social media

Copied To Clipboard