الملاحظات تحرير

Submit Q# jobs to Azure Quantum

  • مقالة
  • قراءة خلال 11 دقائق

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.

Prerequisites

Create a new Notebook in your workspace

  1. Log in to the Azure portal and select a workspace.
  2. In the left blade, select Notebooks.
  3. Click My Notebooks and click Add New.
  4. In Kernel Type, select IQ#.
  5. 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:

Prerequisites

Quantum computing with Q# and Python

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

  2. If you've never used Q# with Python, follow the steps in Write a Q# and Python programs.

  3. 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);
    }
}

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

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

  6. 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'}]

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

Quantum computing with Q# Jupyter Notebooks

  1. Run jupyter notebook from the terminal where your conda environment is activated. This starts the notebook server and opens Jupyter in a browser.

  2. Create your Q# notebook (via New → Q#) and write your Q# program.

  3. If you've never used Q# with Jupyter, follow the steps in Run a Q# program.

  4. 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;
}

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

  6. 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:

Prerequisites

Ensure that the following items are installed on your computer:

Submit a job to Azure Quantum with the Azure CLI

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

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.

  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. You can see all the Azure Quantum workspaces in your subscription with the following command:

    az quantum workspace list

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

  1. 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                                       Status     Average Queue Time
----------  ----------------------------------------------  ---------  --------------------
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.paralleltempering.fpga                Available  0
Microsoft   microsoft.simulatedannealing.fpga               Available  0
ionq        ionq.qpu                                        Available  0
ionq        ionq.simulator                                  Available  0

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

  3. You can use the job ID to track its status:

    az quantum job show -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.

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

     az quantum job output -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 Microsoft 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 -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.

Next steps