Manage quantum workspaces with the Azure CLI

In this guide, learn to use the Azure Command-Line Interface (Azure CLI) to create Azure Quantum workspaces and the required resource groups and storage accounts, and start running your quantum applications in Azure Quantum.

Prerequisites

To use the Azure Quantum service, you need:

• An Azure account with an active subscription. If you don’t have an Azure account, register for free and sign up for a pay-as-you-go subscription.
• An Azure resource group where the quantum workspace lives.
• A storage account in the resource group to be associated with the quantum workspace. Multiple workspaces can be associated with the same account.
• The Azure CLI.
• The Microsoft Quantum Development Kit.

Environment setup

1. Install the Azure CLI quantum extension. Open a command prompt and run the following command, which also upgrades the extension if a previous version is already installed:

   az extension add --upgrade -n quantum
   

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

   az login
   

3. Specify the subscription you want to use.

   az account set -s <Your subscription ID>
   

4. If this is the first time creating quantum workspaces in your subscription, register the resource provider with this command:

   az provider register --namespace Microsoft.Quantum
   

Create an Azure Quantum workspace

To create a new Azure Quantum workspace, you need to know:

• The location or Azure region name to create the resource. You can use the list of regions and their resource manager codes supported by the Azure CLI tool, for example, westus.
• The resource group associated with the new workspace, for example, MyResourceGroup.
• A storage account in the same resource group and subscription as the quantum workspace. It's possible to create a new storage account from the Az CLI tool, for example, MyStorageAccount.
• The name of the quantum workspace to create, for example, MyQuantumWorkspace.
• The list of Azure Quantum providers to use in the workspace. A provider offers a set of plans, each of them representing a plan with associated terms and conditions, costs, and quotas. To create workspaces, you need to specify the corresponding plan along with the providers.

If you already know the provider and plan names to use in your workspace, you can skip to step four, below. If you want to start with the providers that offer free credit, you can enter the following command:

az quantum workspace create \
   -l MyLocation \
   -g MyResourceGroup \
   -w MyQuantumWorkspace \
   -a MyStorageAccount

You might be prompted to accept terms of use. Enter Y to accept the terms. Note that the -r parameter shown in step four, below, wasn't required.

If you need to determine which providers and plans to use, proceed as follows:

1. To retrieve the list of available quantum providers, use the list command (this example uses westus as the location):

   az quantum offerings list \
        -l westus \
        -o table
   

   Tip

   If want to see which providers give free credit, use the --autoadd-only parameter, for example:
   az quantum offerings list --autoadd-only -l westus -o table
   As mentioned previously, those providers are automatically added to your workspace. You don't need to specify them with the -r parameter.

2. Once you determine the provider and plan to include in your workspace, you can review terms using the show-terms command (adding your MyProviderID and MyPlan as example values):

   az quantum offerings show-terms \
        -l westus \
        -p MyProviderId \
        -k MyPlan
   

3. The output of the show-terms command includes a Boolean field accepted that shows whether the terms for this provider have been accepted already or not, as well as a link to the license terms to review. If you decide to accept those terms, use the accept-terms command to record your acceptance.

   az quantum offerings accept-terms \
        -l westus \
        -p MyProviderId \
        -k MyPlan
   

4. Once you have reviewed and accepted all required terms and conditions, you can create your workspace using the create command, specifying a list of provider and plan combinations separated by commas, as in the following example:

   az quantum workspace create \
        -l westus \
        -g MyResourceGroup \
        -w MyQuantumWorkspace \
        -a MyStorageAccount \
        -r "MyProvider1/MyPlan1, MyProvider2/MyPlan2"
   

Once you create a workspace, you can still add or remove providers using the Azure portal.

Change the default storage account for a quantum workspace

If you need to change the default storage account for an existing workspace, you can use the create command, specifying all the current properties along with the new storage account. The following example uses the same settings as the workspace created in the previous example:

az quantum workspace create \
   -l westus \
   -g MyResourceGroup \
   -w MyQuantumWorkspace \
   -a MyNEWStorageAccount \
   -r "MyProvider1/MyPlan1, MyProvider2/MyPlan2"

Delete a quantum workspace

If you know the name and resource group of a quantum workspace you want to delete, you can do it with the delete command (using the same names as the previous example):

az quantum workspace delete \
   -g MyResourceGroup \
   -w MyQuantumWorkspace

After you delete a workspace, it is still listed while it's being deleted in the cloud. However, the provisioningState property of the workspace changes immediately to indicate that it's being deleted. You can see this information by using the show command:

az quantum workspace show \
   -g MyResourceGroup \
   -w MyQuantumWorkspace

az quantum workspace delete

Next steps

Now that you can create and delete workspaces, learn about the different targets to run quantum algorithms in Azure Quantum.