Creating CLI extension for Azure Quantum

.github/CODEOWNERS

@@ -116,6 +116,8 @@
 
 /src/account/ @zikalino
 
+/src/quantum/ @anpaz-msft
+
 /src/datashare/ @fengzhou-msft
 
 /src/k8sconfiguration/ @NarayanThiru

src/quantum/HISTORY.rst

@@ -0,0 +1,9 @@
+.. :changelog:
+
+Release History
+===============
+
+0.11.2906.2
+++++++
+* Initial release. Version intended to work with Azure Quantum Private Preview 
+  and with QDK version 0.11.2906.*

src/quantum/README.rst

@@ -0,0 +1,161 @@
+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/
+
+
+# Using the `az quantum` extension to list and manage jobs in Azure Quantum
+
+1. Log in to Azure using your credentials.
+   ```dotnetcli
+   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. You can see all the Azure Quantum workspaces in your subscription with the `az quantum workspace list` command:
+   ```dotnetcli
+   az quantum workspace list
+   ```
+
+3. 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.
+   ```dotnetcli
+    az quantum workspace set -g MyResourceGroup -w MyWorkspace  -o table
+
+    Location     Name                               ResourceGroup
+    -----------  ---------------------------------  --------------------------------
+    westus       ws-yyyyyy                          rg-yyyyyyyyy
+   ```
+
+4. You can check the current default workspace with the command `az quantum workspace show`.
+
+   ```dotnetcli
+    az quantum workspace show -o table
+
+    Location     Name                               ResourceGroup
+    -----------  ---------------------------------  --------------------------------
+    westus       ws-yyyyyy                          rg-yyyyyyyyy
+   ```
+
+5. You can see all the jobs submitted a workspace using `az quantum job list`.
+
+   ```dotnetcli
+    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.
+
+6. You can use the ID of the job to track its status:
+   ```dotnetcli
+    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
+   ```
+
+7. Once the job finishes you can visualize the job's results with `az quantum job output`:
+   ```dotnetcli
+    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   ▐█████                  |
+   ```
+
+
+
+# Submitting 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:
+
+```qsharp
+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 `az quantum job submit`:
+
+```
+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:
+```
+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 results was measured. In the example above
+the result `[0,1]` was observed 75% of the times.
+
+
+Finally, you can use `az quantum execute` as a shortcut for both, submitting and getting the results of execution.
+```
+az quantum execute --target-id ionq.simulator --job-name Hello2 -o table
+.....
+Result    Frequency
+--------  -----------  -------------------------
+[0,0]     0.25000000   ▐█████                  |
+[0,1]     0.75000000   ▐████████████████       |
+```
+
+

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

src/quantum/azext_quantum/_client_factory.py

@@ -0,0 +1,51 @@
+# --------------------------------------------------------------------------------------------
+# 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
+
+
+def is_env(name):
+    return 'AZURE_QUANTUM_ENV' in os.environ and os.environ['AZURE_QUANTUM_ENV'] == name
+
+
+def base_url():
+    if 'AZURE_QUANTUM_BASEURL' in os.environ:
+        return os.environ['AZURE_QUANTUM_BASEURL']
+    if is_env('canary'):
+        return "https://app-jobs-canarysouthcentralus.azurewebsites.net/"
+    return "https://app-jobscheduler-prod.azurewebsites.net/"
+
+
+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):
+    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())
+
+
+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):
+    return cf_quantum(cli_ctx, subscription_id, resource_group_name, workspace_name).providers
+
+
+def cf_jobs(cli_ctx, subscription_id=None, resource_group_name=None, workspace_name=None):
+    return cf_quantum(cli_ctx, subscription_id, resource_group_name, workspace_name).jobs

src/quantum/azext_quantum/_help.py

@@ -0,0 +1,63 @@
+# coding=utf-8
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from knack.help_files import helps  # pylint: disable=unused-import
+
+helps['quantum'] = """
+    type: group
+    short-summary: Manage Azure Quantum Workspaces and submit jobs to Azure Quantum Providers.
+"""
+
+helps['quantum job'] = """
+    type: group
+    short-summary: Manage jobs for Azure Quantum.
+    examples:
+      - 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
+        text: |-
+            az quantum job submit -g MyResourceGroup -w MyWorkspace \\
+               --job-name MyJob 
+      - name: Get the status of an Azure Quantum job
+        text: |-
+            az quantum job show -g MyResourceGroup -w MyWorkspace \\
+                -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy --query status
+      - name: Print the results of a successful Azure Quantum job
+        text: |-
+            az quantum job output -g MyResourceGroup -w MyWorkspace \\
+                -id yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy -o table
+"""
+
+helps['quantum target'] = """
+    type: group
+    short-summary: Manage execution targets for Azure Quantum workspaces.
+    examples:
+      - name: Get the list of targets available in a Azure Quantum workspaces
+        text: |-
+            az quantum target list -g MyResourceGroup -w MyWorkspace
+      - name: Select a default when submitting jobs to Azure Quantum
+        text: |-
+            az quantum target set -t target-id
+      - name: Show the currently selected default target
+        text: |-
+            az quantum target show
+"""
+
+helps['quantum workspace'] = """
+    type: group
+    short-summary: Manage Azure Quantum workspaces.
+    examples:
+      - name: Get the list of Azure Quantum workspaces available
+        text: |-
+            az quantum workspace list
+      - name: Select a default Azure Quantum workspace for future commands
+        text: |-
+            az quantum workspace set -g MyResourceGroup -w MyWorkspace
+      - name: Show the currently selected default Azure Quantum workspace
+        text: |-
+            az quantum workspace show
+"""

src/quantum/azext_quantum/_params.py

@@ -0,0 +1,45 @@
+# --------------------------------------------------------------------------------------------
+# 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
+
+from knack.arguments import CLIArgumentType
+
+
+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)
+    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.')
+    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 execution of the program.')
+    shots_type = CLIArgumentType(help='The number of times to execute the Q# program on the given target.')
+    no_build_type = CLIArgumentType(help='If specified, the Q# program is not built before submitting.')
+
+    with self.argument_context('quantum workspace') as c:
+        c.argument('workspace_name', workspace_name_type)
+
+    with self.argument_context('quantum target') as c:
+        c.argument('workspace_name', workspace_name_type)
+        c.argument('target_id', options_list=['--target-id', '-t'], help='Target id.')
+
+    with self.argument_context('quantum job') as c:
+        c.argument('workspace_name', workspace_name_type)
+        c.argument('job_id', options_list=['--job-id', '-id'], help='Job id.')
+        c.argument('target_id', target_id_type)
+        c.argument('project', project_type)
+        c.argument('job_name', job_name_type)
+        c.argument('shots', shots_type)
+        c.argument('no_build', no_build_type)
+
+    with self.argument_context('quantum job submit') as c:
+        c.positional('program_args', program_args_type)
+
+    with self.argument_context('quantum execute') as c:
+        c.argument('workspace_name', workspace_name_type)
+        c.argument('target_id', target_id_type)
+        c.argument('project', project_type)
+        c.argument('job_name', job_name_type)
+        c.argument('shots', shots_type)
+        c.argument('no_build', no_build_type)
+        c.positional('program_args', program_args_type)