diff --git a/src/quantum/README.rst b/src/quantum/README.rst index 9f7e5a27b5b..2e07b870ca4 100644 --- a/src/quantum/README.rst +++ b/src/quantum/README.rst @@ -14,8 +14,50 @@ To learn more about quantum computing and Microsoft's Quantum Development Kit, v https://docs.microsoft.com/quantum/ -Using the `az quantum` extension to list and manage jobs in Azure Quantum -========================================================================= +Creating Q# programs for execution from the command line +======================================================== + +Prerequisites +------------- + +- You need to have an Azure Quantum workspace in your subscription. +- Install the [Quantum Development Kit](https://docs.microsoft.com/quantum/install-guide/standalone), if you haven't already. + + +Write your quantum application +------------------------------ + +First you need to have the Q# quantum application that you want to execute in +Azure Quantum. + +.. tip:: + If this is the first time for you to create Q# quantum applications, you can learn how + in our [Microsoft Learn module](https://docs.microsoft.com/en-us/learn/modules/qsharp-create-first-quantum-development-kit/). + +In this case we will use a simple quantum random bit generator. We create a Q# +project and substitute the content of `Program.qs` with the following code: + +.. code-block:: + + 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. + + +Prepare to submit and manage jobs in Azure Quantum using the `az quantum` extension +=================================================================================== 1. Log in to Azure using your credentials. @@ -28,32 +70,42 @@ Using the `az quantum` extension to list and manage jobs in Azure Quantum subscription you want to use. You can do this with the command `az account set -s `. -2. Install the Quantum extension for the Azure CLI +2. Install the Quantum extension for the Azure CLI. .. code-block:: az extension add --name quantum -3. You can see all the Azure Quantum workspaces in your subscription with the `az quantum workspace list` command: +3. You can see all the Azure Quantum workspaces in your subscription with the `az quantum workspace list` command. + At this time, you need to create and set up your workspaces using the Azure Portal, please refer to the documentation + for Azure Quantum for details on this and how to choose providers. .. code-block:: az quantum workspace list -4. You can use `quantum workspace set` to select a default workspace you want to use - to list and submit jobs. Note that you also need to specify the resource group. +4. You can use `quantum workspace set` to select a default workspace you want to use to list and submit jobs. + Note that you also need to specify the resource group. If you set a default workspace by providing a resource group, + workspace name and location, you don't need to include those parameters in commands #5 to #8 below. + Anternatively, you can include them in each call. .. code-block:: - az quantum workspace set -g MyResourceGroup -w MyWorkspace -o table + az quantum workspace set -g MyResourceGroup -w MyWorkspace -l MyLocation -o table Location Name ResourceGroup ----------- --------------------------------- -------------------------------- westus ws-yyyyyy rg-yyyyyyyyy +.. note: + Commands below assume that a default workspace has been set. If you prefer to specify it + for each call, include the following parameters with commands below: + `-g MyResourceGroup -w MyWorkspace -l MyLocation` + + 5. You can check the current default workspace with command `az quantum workspace show`. .. code-block:: @@ -65,7 +117,20 @@ Using the `az quantum` extension to list and manage jobs in Azure Quantum westus ws-yyyyyy rg-yyyyyyyyy -6. You can see all the jobs submitted to a workspace using `az quantum job list`. +6. For this example we are going to use IonQ as the provider and the `ionq.simulator` as target. + To submit the job to the currently selected default quantum workspace, run the following from the directory + where you have the project created previously. + + .. code-block:: + + az quantum job submit --target-id ionq.simulator --job-name Hello -o table + + Name Id Status Target Submission time + ----- ------------------------------------ -------- -------------- --------------------------------- + Hello yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy Waiting ionq.simulator 2020-06-17T17:07:07.3484901+00:00 + + +7. You can see all the jobs submitted to a workspace using `az quantum job list`. .. code-block:: @@ -78,7 +143,7 @@ Using the `az quantum` extension to list and manage jobs in Azure Quantum The console will output the information about the job, including the ID of the job. -7. You can use the ID of the job to track its status. +8. You can use the ID of the job to track its status. .. code-block:: @@ -89,7 +154,7 @@ Using the `az quantum` extension to list and manage jobs in Azure Quantum yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy Waiting MyProvider.MyTarget 2020-06-12T14:20:18.6109317+00:00 -8. Once the job finishes you can visualize the job's results with `az quantum job output`: +9. Once the job finishes (i.e. it's in a **Successful** state) you can visualize the job's results. .. code-block:: @@ -103,85 +168,19 @@ Using the `az quantum` extension to list and manage jobs in Azure Quantum [1,1] 0.25000000 ▐█████ | -Submitting Q# programs for execution from the command line -========================================================== + The output shows a histogram with the frequency a specific result was measured. In the example above, + the result `[0,1]` was observed 25% of the times. -Prerequisites -------------- -- You need to have an Azure Quantum workspace in your subscription. -- Install the [Quantum Development Kit](https://docs.microsoft.com/quantum/install-guide/standalone), if you haven't already. - - -Write your quantum application ------------------------------- - -First you need to have the Q# quantum application that you want to execute in -Azure Quantum. - -.. tip:: - If this is the first time for you to create Q# quantum applications, you can learn how - in our [Microsoft Learn module](https://docs.microsoft.com/en-us/learn/modules/qsharp-create-first-quantum-development-kit/). - -In this case we will use a simple quantum random bit generator. We create a Q# -project and substitute the content of `Program.qs` with the following code: - -.. code-block:: - - namespace RandomBit { - - open Microsoft.Quantum.Canon; - open Microsoft.Quantum.Intrinsic; - open Microsoft.Quantum.Measurement; - - @EntryPoint() - operation GenerateRandomBit() : Result { - using (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 target. To submit the job to the currently selected -default quantum workspace, run `az quantum job submit`: - -.. code-block:: +10. Alternatively, you can run a job synchronously and wait for it to complete. - az quantum job submit --target-id ionq.simulator --job-name Hello -o table - - Name Id Status Target Submission time - ----- ------------------------------------ -------- -------------- --------------------------------- - Hello yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy Waiting ionq.simulator 2020-06-17T17:07:07.3484901+00:00 - -Once the job completes (i.e. it's in a **Successful** state), use `az quantum job output` to see the results: - -.. code-block:: - - az quantum job output -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table - - Result Frequency - -------- ----------- ------------------------- - [0,0] 0.25000000 ▐█████ | - [0,1] 0.75000000 ▐████████████████ | - -The output shows a histogram with the frequency a specific result was measured. In the example above, -the result `[0,1]` was observed 75% of the times. + .. code-block:: + az quantum execute --target-id ionq.simulator --job-name Hello2 -o table + + Result Frequency + -------- ----------- ------------------------- + [0,0] 0.25000000 ▐█████ | + [0,1] 0.75000000 ▐████████████████ | -Finally, you can use `az quantum execute` as a shortcut for both, submitting and getting the results of execution. -.. code-block:: - - az quantum execute --target-id ionq.simulator --job-name Hello2 -o table - - Result Frequency - -------- ----------- ------------------------- - [0,0] 0.25000000 ▐█████ | - [0,1] 0.75000000 ▐████████████████ | diff --git a/src/quantum/azext_quantum/_help.py b/src/quantum/azext_quantum/_help.py index 1df681edd3d..895121ffa9c 100644 --- a/src/quantum/azext_quantum/_help.py +++ b/src/quantum/azext_quantum/_help.py @@ -11,37 +11,115 @@ short-summary: Manage Azure Quantum Workspaces and submit jobs to Azure Quantum Providers. """ +helps['quantum execute'] = """ + type: command + short-summary: Submit a job to run on Azure Quantum, and waits for the result. + examples: + - name: Submit the Q# program from the current folder and wait for the result. + text: |- + az quantum execute -g MyResourceGroup -w MyWorkspace -l MyLocation +""" + +helps['quantum run'] = """ + type: command + short-summary: Equivalent to `az quantum execute` + examples: + - name: Submit the Q# program from the current folder and wait for the result. + text: |- + az quantum run -g MyResourceGroup -w MyWorkspace -l MyLocation +""" + helps['quantum job'] = """ type: group short-summary: Manage jobs for Azure Quantum. +""" + +helps['quantum job list'] = """ + type: command + short-summary: Get the list of jobs in a Quantum Workspace. examples: - - name: Get the list of jobs from an Azure Quantum workspace + - name: Get the list of jobs from an Azure Quantum workspace. text: |- - az quantum job list -g MyResourceGroup -w MyWorkspace - - name: Submit the Q# program from the current folder + az quantum job list -g MyResourceGroup -w MyWorkspace -l MyLocation +""" + +helps['quantum job output'] = """ + type: command + short-summary: Get the results of running a Q# job. + examples: + - name: Print the results of a successful Azure Quantum job. text: |- - az quantum job submit -g MyResourceGroup -w MyWorkspace \\ - -l MyLocation --job-name MyJob - - name: Get the status of an Azure Quantum job + az quantum job output -g MyResourceGroup -w MyWorkspace -l MyLocation \\ + -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table +""" + +helps['quantum job show'] = """ + type: command + short-summary: Get the job's status and details. + examples: + - name: Get the status of an Azure Quantum job. text: |- - az quantum job show -g MyResourceGroup -w MyWorkspace \\ + az quantum job show -g MyResourceGroup -w MyWorkspace -l MyLocation \\ -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy --query status - - name: Print the results of a successful Azure Quantum job +""" + +helps['quantum job submit'] = """ + type: command + short-summary: Submit a Q# project to run on Azure Quantum. + examples: + - name: Submit the Q# program from the current folder. text: |- - az quantum job output -g MyResourceGroup -w MyWorkspace \\ - -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table + az quantum job submit -g MyResourceGroup -w MyWorkspace -l MyLocation \\ + -l MyLocation --job-name MyJob +""" + +helps['quantum job wait'] = """ + type: command + short-summary: Place the CLI in a waiting state until the job finishes running. + examples: + - name: Wait for completion of a job for 60 seconds. + text: |- + az quantum job wait -g MyResourceGroup -w MyWorkspace -l MyLocation \\ + -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy --max-poll-wait-secs 60 -o table """ + helps['quantum target'] = """ type: group short-summary: Manage targets for Azure Quantum workspaces. +""" + +helps['quantum target clear'] = """ + type: command + short-summary: Clear the default target-id. + examples: + - name: Clear the default target-id. + text: |- + az quantum target clear +""" + +helps['quantum target list'] = """ + type: command + short-summary: Get the list of providers and their targets in an Azure Quantum workspace. examples: - name: Get the list of targets available in a Azure Quantum workspaces text: |- az quantum target list -g MyResourceGroup -w MyWorkspace -l MyLocation - - name: Select a default when submitting jobs to Azure Quantum +""" + +helps['quantum target set'] = """ + type: command + short-summary: Select the default target to use when submitting jobs to Azure Quantum. + examples: + - name: Select a default when submitting jobs to Azure Quantum. text: |- az quantum target set -t target-id +""" + +helps['quantum target show'] = """ + type: command + short-summary: Get the details of the given (or current) target to use when submitting jobs to Azure Quantum. + examples: - name: Show the currently selected default target text: |- az quantum target show @@ -50,23 +128,82 @@ helps['quantum workspace'] = """ type: group short-summary: Manage Azure Quantum workspaces. +""" + +helps['quantum workspace clear'] = """ + type: command + short-summary: Clear the default Azure Quantum workspace. examples: - - name: Get the list of Azure Quantum workspaces available + - name: Clear the default Azure Quantum workspace if previously set. text: |- - az quantum workspace list - - name: Create a new Azure Quantum workspace + az quantum workspace clear +""" + +helps['quantum workspace create'] = """ + type: command + short-summary: Create a new Azure Quantum workspace. + examples: + - name: Create a new Azure Quantum workspace. text: |- - az quantum workspace create -g MyResourceGroup -w MyWorkspace -l MyLocation -sa MyStorageAccountName - - name: Delete an Azure Quantum workspace that is no longer being used + az quantum workspace create -g MyResourceGroup -w MyWorkspace -l MyLocation \\ + -sa MyStorageAccountName +""" + +helps['quantum workspace delete'] = """ + type: command + short-summary: Delete the given (or current) Azure Quantum workspace. + examples: + - name: Delete an Azure Quantum workspace by name and group. text: |- az quantum workspace delete -g MyResourceGroup -w MyWorkspace - - name: Select a default Azure Quantum workspace for future commands + - name: Delete and clear the default Azure Quantum workspace (if one has been set). text: |- - az quantum workspace set -g MyResourceGroup -w MyWorkspace -l MyLocation - - name: List the quota information of a workspace + az quantum workspace delete +""" + +helps['quantum workspace list'] = """ + type: command + short-summary: Get the list of Azure Quantum workspaces available. + examples: + - name: Get the list of all Azure Quantum workspaces available. + text: |- + az quantum workspace list + - name: Get the list Azure Quantum workspaces available in a location. + text: |- + az quantum workspace list -l MyLocation + +""" + +helps['quantum workspace quotas'] = """ + type: command + short-summary: List the quotas for the given (or current) Azure Quantum workspace. + examples: + - name: List the quota information of the default workspace if set. + text: |- + az quantum workspace quotas + - name: List the quota information of a specified Azure Quantum workspace. text: |- az quantum workspace quotas -g MyResourceGroup -w MyWorkspace -l MyLocation - - name: Show the currently selected default Azure Quantum workspace +""" + +helps['quantum workspace set'] = """ + type: command + short-summary: Select a default Azure Quantum workspace for future commands. + examples: + - name: Set the default Azure Quantum workspace. text: |- - az quantum workspace show + az quantum workspace set -g MyResourceGroup -w MyWorkspace -l MyLocation """ + +helps['quantum workspace show'] = """ + type: command + short-summary: Get the details of the given (or current) Azure Quantum workspace. + examples: + - name: Show the currently selected default Azure Quantum workspace. + text: |- + az quantum workspace show + - name: Show the details of a provided Azure Quantum workspace. + text: |- + az quantum workspace show -g MyResourceGroup -w MyWorkspace -l MyLocation + +""" \ No newline at end of file diff --git a/src/quantum/azext_quantum/_params.py b/src/quantum/azext_quantum/_params.py index d0da06c44e1..705634d427c 100644 --- a/src/quantum/azext_quantum/_params.py +++ b/src/quantum/azext_quantum/_params.py @@ -11,7 +11,7 @@ def load_arguments(self, _): workspace_name_type = CLIArgumentType(options_list=['--workspace-name', '-w'], help='Name of the Quantum Workspace. You can configure the default workspace using `az quantum workspace set`.', id_part=None, required=False) storage_account_name_type = CLIArgumentType(options_list=['--storage_account', '-sa'], help='Name of the storage account to be used by a quantum workspace.') program_args_type = CLIArgumentType(nargs='*', help='List of arguments expected by the Q# operation specified as --name=value after `--`.') - target_id_type = CLIArgumentType(options_list=['--target-id', '-t'], help='Target id.') + target_id_type = CLIArgumentType(options_list=['--target-id', '-t'], help='Execution engine for quantum computing jobs. When a workspace is configured with a set of provider, they each enable one or more targets.') project_type = CLIArgumentType(help='The location of the Q# project to submit. Defaults to current folder.') job_name_type = CLIArgumentType(help='A friendly name to give to this run of the program.') shots_type = CLIArgumentType(help='The number of times to run the Q# program on the given target.') diff --git a/src/quantum/azext_quantum/operations/job.py b/src/quantum/azext_quantum/operations/job.py index f10d24c2d08..d5a31cb89e0 100644 --- a/src/quantum/azext_quantum/operations/job.py +++ b/src/quantum/azext_quantum/operations/job.py @@ -147,10 +147,13 @@ def _parse_blob_url(url): from urllib.parse import urlparse o = urlparse(url) - account_name = o.netloc.split('.')[0] - container = o.path.split('/')[-2] - blob = o.path.split('/')[-1] - sas_token = o.query + try: + account_name = o.netloc.split('.')[0] + container = o.path.split('/')[-2] + blob = o.path.split('/')[-1] + sas_token = o.query + except IndexError: + raise CLIError(f"Failed to parse malformed blob URL: {url}") return { "account_name": account_name, @@ -205,18 +208,19 @@ def has_completed(job): client = cf_jobs(cmd.cli_ctx, info.subscription, info.resource_group, info.name, info.location) # TODO: LROPoller... - w = False + wait_indicators_used = False poll_wait = 0.2 job = client.get(job_id) while not has_completed(job): print('.', end='', flush=True) - w = True + wait_indicators_used = True time.sleep(poll_wait) job = client.get(job_id) poll_wait = max_poll_wait_secs if poll_wait >= max_poll_wait_secs else poll_wait * 1.5 - if w: + if wait_indicators_used: + # Insert a new line if we had to display wait indicators. print("") return job diff --git a/src/quantum/azext_quantum/operations/target.py b/src/quantum/azext_quantum/operations/target.py index 78dff608b7e..9f4e4d8ca51 100644 --- a/src/quantum/azext_quantum/operations/target.py +++ b/src/quantum/azext_quantum/operations/target.py @@ -62,7 +62,7 @@ def list(cmd, resource_group_name=None, workspace_name=None, location=None): def clear(cmd): """ - Unset the default target-id. + Clear the default target-id. """ info = TargetInfo(cmd) info.clear()