Creating CLI extension for Azure Quantum (Azure#1879)

* Azure quantum extension v0 (#2) Initial version. * Fixing style issues * Incorporating feedback (#6) * readme * feedback * Help * Make storage account optional (#7) * Storage is now optional (#8) * Making storage an argument, not an env variable (#9) * Adding implementation of 'az quantum workspace delete' command. * Setting new temporary version. * Fixing missing file in test change * Adding details to README.md (#5) * Updating generated files for Azure Quantum resource manager from new swagger file version * Remove manual edit of generated file. * Updating generated files for Azure Quantum data plane from new swagger file version * Updating generated files for Azure Quantum resource manager from new swagger file version. (2020-11-06) (#13) * Adding implementation of 'az quantum workspace create' command. (#14) Adding initial implementation of 'az quantum workspace create' command. ----------------------------------- Command az quantum workspace create : Creates a new Azure Quantum workspace. Command group 'quantum' is in preview. It may be changed/removed in a future release. Arguments --location -l : Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>. --resource-group -g : Name of resource group. You can configure the default group using az configure --defaults group=<name>. --storage_account -sa : Name of the storage account to be used by a quantum workspace. --workspace-name -w : Name of the Quantum Workspace. You can configure the default workspace using az quantum workspace set. * Update Azure CLI quantum extension to multi-region (#17) This change will set the URL for the data plan API accordingly with a location parameter specified as part of the command. * Updating swagger files per commit 44563991425d862ba4e8090a2b5b6caf8333600c in azure-rest-api-specs-pr. (#16) Updating swagger files per commit 44563991425d862ba4e8090a2b5b6caf8333600c in azure-rest-api-specs-pr. * Fixing tests for multi-region URL change on Az CLI quantum extension (#19) Fixing tests for multi-region URL change on Az CLI quantum extension * Incorporating ARM feedback (#18) * Picking up latest changes from swagger after ARM feedback * updated create_or_update * run command * Setting default location in workspace calls if not specified (#20) * updating python azure quantum rest client (#21) * Update generated files from swagger file (Version 2021-01-11) (#22) * Hot fixes on December 2020 release of Azure CLI extension (#23) * Fixing issue with over specification of location * Updating version information of extension * Update CLI with generated clients from more recent swagger files (#24) - Data plane updated to official swagger file (2021-01-11 19:01:32 UTC) on azure-rest-api-specs @ 98ae52b. - Resource manager updated to candidate swagger file (2021-01-15 19:35:41 UTC) on anpaz:quantum/resource-manager @ a9a9e271c13500aa54fdbb1bcb656eb61d82d38b. * Update src/quantum/README.rst Co-authored-by: Feiyue Yu <[email protected]> * Update src/quantum/README.rst Co-authored-by: Feiyue Yu <[email protected]> * Update src/quantum/README.rst Co-authored-by: Feiyue Yu <[email protected]> * Update src/quantum/README.rst Co-authored-by: Feiyue Yu <[email protected]> * Require location as a mandatory parameter in workspace specification (#25) * Make location mandatory in commands * Update test recordings * Resetting the version history for the released version. * Fix description of workspace clear command * Updatig Readme file to RST format. * Update Readme file per pull request comments. * Fixing az quantum run and execute commands to include location parameter * Performing role assignment on storage account on workspace creation. (#29) * Add warning message about providers during workspace creation (#30) * Enable command az quantum workspace quotas (#31) * Removing extra space in Readme.rst Co-authored-by: Feiyue Yu <[email protected]> * Fix punctuation in Readme.rst Co-authored-by: Feiyue Yu <[email protected]> * Update src/quantum/README.rst Co-authored-by: Feiyue Yu <[email protected]> * Update src/quantum/azext_quantum/_params.py Co-authored-by: Feiyue Yu <[email protected]> * First round of code review feedback on Readme.rst * Improve code readability on job commands * Avoid IndexError in case of malformed URL * Extended info on targetId parameter * Add help to each individual command * Reorganize sections in Readme.rst and merge in a single set of instructions. * Static analysis fixes * Fix CLI Linter errors * Fix CLI Linter errors. Part 2 * Fix typo in show command. * Fix show command for Linter * Use standard name for show command method * Modify workspace create test to skip role assignment * Update tests with workspace names used currently. * Update test recordings. * Set subscription for the recordings. * Update test recordings. * Update QDK version number * Remove asserts and checks for subscription * Experiment: Remove check for preview subscription * Refresh recordings with current test values. * Update recordings after typo fix. * Remove commented out API that references subscription * Enable QuantumJobsScenarioTest.test_submit_args only on live mode Co-authored-by: Ricardo Espinoza <[email protected]> Co-authored-by: Feiyue Yu <[email protected]>
anpaz · Feb 1, 2021 · 12f5b10 · 12f5b10
1 parent e12584e
commit 12f5b10
Show file tree

Hide file tree

Showing 115 changed files with 7,100 additions and 0 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -120,6 +120,8 @@
 
 /src/account/ @arrownj @jiasli @fengzhou-msft
 
+/src/quantum/ @anpaz-msft
+
 /src/datashare/ @fengzhou-msft
 
 /src/ssh/ @rlrossiter @danybeam @arrownj

diff --git a/linter_exclusions.yml b/linter_exclusions.yml
@@ -1828,6 +1828,21 @@ providerhub resource-type-registration create:
     template_deployment_options:
       rule_exclusions:
       - option_length_too_long
+quantum execute:
+  parameters:
+    program_args:
+      rule_exclusions:
+        - no_positional_parameters
+quantum run:
+  parameters:
+    program_args:
+      rule_exclusions:
+        - no_positional_parameters
+quantum job submit:
+  parameters:
+    program_args:
+      rule_exclusions:
+        - no_positional_parameters
 repos import create:
   parameters:
     git_service_endpoint_id:

diff --git a/src/quantum/HISTORY.rst b/src/quantum/HISTORY.rst
@@ -0,0 +1,8 @@
+.. :changelog:
+
+Release History
+===============
+
+0.1.0
+++++++
+* Initial release. Version intended to work with QDK version 0.15.2101125897
diff --git a/src/quantum/README.rst b/src/quantum/README.rst
@@ -0,0 +1,186 @@
+=======================================
+Microsoft Azure CLI 'quantum' Extension
+=======================================
+
+Azure Quantum is the first open Quantum computing platform. It offers a range of services
+from quantum hardware to full-state simulators and quantum inspired optimizations,
+providing developers and customers access to the most competitive quantum offering
+on the market.
+
+To learn more about azure quantum, visit:
+https://azure.microsoft.com/en-us/services/quantum/
+
+To learn more about quantum computing and Microsoft's Quantum Development Kit, visit:
+https://docs.microsoft.com/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.
+
+   .. code-block:: 
+
+      az login
+
+   .. note::
+      In case you have more than one subscription associated with your Azure account you must specify the 
+      subscription you want to use. You can do this with the command `az account set -s <Your subscription ID>`.
+
+
+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.
+   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. 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 -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::
+
+      az quantum workspace show -o table
+
+      Location     Name                               ResourceGroup
+      -----------  ---------------------------------  --------------------------------
+      westus       ws-yyyyyy                          rg-yyyyyyyyy
+
+
+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::
+
+      az quantum job list -o table
+
+      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 information about the job, including the ID of the job.
+
+
+8. You can use the ID of the job to track its status.
+
+   .. code-block::
+
+      az quantum job show -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table
+
+      Id                                    State    Target          Submission time
+      ------------------------------------  -------  --------------  ---------------------------------
+      yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy  Waiting  MyProvider.MyTarget  2020-06-12T14:20:18.6109317+00:00
+
+
+9. Once the job finishes (i.e. it's in a **Successful** state) you can visualize the job's results.
+
+   .. code-block::
+
+      az quantum job output -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table
+   
+      Result    Frequency
+      --------  -----------  -------------------------
+      [0,0]     0.25000000   ▐█████                  |
+      [1,0]     0.25000000   ▐█████                  |
+      [0,1]     0.25000000   ▐█████                  |
+      [1,1]     0.25000000   ▐█████                  |
+
+
+   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.
+
+
+10. Alternatively, you can run a job synchronously and wait for it to complete.
+
+    .. 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/__init__.py b/src/quantum/azext_quantum/__init__.py
@@ -0,0 +1,26 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core import AzCommandsLoader
+
+import azext_quantum._help  # pylint: disable=unused-import
+
+
+class QuantumCommandsLoader(AzCommandsLoader):
+
+    def __init__(self, cli_ctx=None):
+        super(QuantumCommandsLoader, self).__init__(cli_ctx=cli_ctx)
+
+    def load_command_table(self, args):
+        from azext_quantum.commands import load_command_table
+        load_command_table(self, args)
+        return self.command_table
+
+    def load_arguments(self, command):
+        from azext_quantum._params import load_arguments
+        load_arguments(self, command)
+
+
+COMMAND_LOADER_CLS = QuantumCommandsLoader
diff --git a/src/quantum/azext_quantum/_client_factory.py b/src/quantum/azext_quantum/_client_factory.py
@@ -0,0 +1,59 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+# pylint: disable=line-too-long
+
+import os
+from ._location_helper import normalize_location
+
+
+def is_env(name):
+    return 'AZURE_QUANTUM_ENV' in os.environ and os.environ['AZURE_QUANTUM_ENV'] == name
+
+
+def base_url(location):
+    if 'AZURE_QUANTUM_BASEURL' in os.environ:
+        return os.environ['AZURE_QUANTUM_BASEURL']
+    if is_env('canary'):
+        return "https://eastus2euap.quantum.azure.com/"
+    normalized_location = normalize_location(location)
+    if is_env('dogfood'):
+        return f"https://{normalized_location}.quantum-test.azure.com/"
+    return f"https://{normalized_location}.quantum.azure.com/"
+
+
+def _get_data_credentials(cli_ctx, subscription_id=None):
+    from azure.cli.core._profile import Profile
+    profile = Profile(cli_ctx=cli_ctx)
+    creds, _, _ = profile.get_login_credentials(subscription_id=subscription_id, resource="https://quantum.microsoft.com")
+    return creds
+
+
+def cf_quantum(cli_ctx, subscription_id=None, resource_group_name=None, workspace_name=None, location=None):
+    from .vendored_sdks.azure_quantum import QuantumClient
+    creds = _get_data_credentials(cli_ctx, subscription_id)
+    return QuantumClient(creds, subscription_id, resource_group_name, workspace_name, base_url=base_url(location))
+
+
+def cf_quantum_mgmt(cli_ctx, *_):
+    from azure.cli.core.commands.client_factory import get_mgmt_service_client
+    from .vendored_sdks.azure_mgmt_quantum import QuantumManagementClient
+    return get_mgmt_service_client(cli_ctx, QuantumManagementClient)
+
+
+def cf_workspaces(cli_ctx, *_):
+    return cf_quantum_mgmt(cli_ctx).workspaces
+
+
+def cf_providers(cli_ctx, subscription_id=None, resource_group_name=None, workspace_name=None, location=None):
+    return cf_quantum(cli_ctx, subscription_id, resource_group_name, workspace_name, location).providers
+
+
+def cf_jobs(cli_ctx, subscription_id=None, resource_group_name=None, workspace_name=None, location=None):
+    return cf_quantum(cli_ctx, subscription_id, resource_group_name, workspace_name, location).jobs
+
+
+def cf_quotas(cli_ctx, subscription_id=None, resource_group_name=None, workspace_name=None, location=None):
+    return cf_quantum(cli_ctx, subscription_id, resource_group_name, workspace_name, location).quotas