Skip to content

Code review feedback #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ricardo-espinoza merged 6 commits into from
Jan 28, 2021
Merged

Code review feedback #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ccadf4a
First round of code review feedback on Readme.rst
ricardo-espinoza Jan 28, 2021
eae418f
Improve code readability on job commands
ricardo-espinoza Jan 28, 2021
0b05b48
Avoid IndexError in case of malformed URL
ricardo-espinoza Jan 28, 2021
f596766
Extended info on targetId parameter
ricardo-espinoza Jan 28, 2021
b0bafff
Add help to each individual command
ricardo-espinoza Jan 28, 2021
8e83036
Reorganize sections in Readme.rst and merge in a single set of instru…
ricardo-espinoza Jan 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 85 additions & 86 deletions src/quantum/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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 <Your subscription ID>`.


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::
Expand All @@ -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::

Expand All @@ -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::

Expand All @@ -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::

Expand All @@ -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 ▐████████████████ |
Loading