AWS Braket service backend (#388)

* Add AWS Braket service devices as backends

* Add AWS Braket service devices as backends. Correct a braket in README

* Add AWS Braket service devices as backends. Pass pycodestyle

* AWS Braket service backend. Corrections as per the review

* AWS Braket service backend. Correct test to use approx instead of ==

* AWS Braket service backend. Add tests to raise the coverage

* AWS Braket service backend. Second review adjustments

* Fix import errors when boto3 is not installed + use warnings.warn()

* Fix condition when setting the number of controls

* Minor adjustments in _awsbraket.py

- Better handling of daggered gates
- Some minor code cleanup

* Make sure that unit tests are skipped if boto3 is not installed

* Rapid fix to make sure that tests can be repeated without errors

* Fixes for _awsbraket.py and its associated tests

- Minor code cleanup
- Modify functional tests to work with and without mapper
- Fix issue when repeating some tests more than once
- Add missing test for case where AWS Braket backend is used as a
  compiler engine

* Minor adjustments to _awsbraket_boto3_client.py and related tests

- Tweak user messages slightly
- Add test to cover missing execution paths

* Remove mapper in Jupyter notebook

* Cleanup tests for _awsbraket.py + remove unneeded catch of TypeError

* Adjust .coveragerc

* Cleanup tests for _awsbraket_boto3_client.py

* Fix erroneous license header

* Mention installing ProjectQ with the 'braket' extra in README

* Remove unneeded call to is_available in AWSBraketBackend + ...

... improve basic functional test.

* Re-indent _awsbraket_boto3_client.py

* Some more cleanup for _awsbraket.py

* Some more cleanup for _awsbraket_boto3_client.py

* Remove trivial mapper in default setup for AWS Braket backend

* Fix test failure

Co-authored-by: Damien Nguyen <[email protected]>

Author: fernandodelaiglesia

.coveragerc

@@ -1,3 +1,4 @@
 [run]
 
 omit = *_test.py
+       *_fixtures.py

.travis.yml

@@ -59,7 +59,7 @@ jobs:
 install:
   - env
   - python3 -m pip install -U pip setuptools wheel
-  - python3 -m pip install -U pybind11 dormouse revkit flaky pytest-cov coveralls
+  - python3 -m pip install -U pybind11 dormouse revkit flaky pytest-cov coveralls boto3
   - python3 -m pip install -r requirements.txt
   - python3 -m pip install -ve .
 

README.rst

@@ -24,7 +24,7 @@ targeting various types of hardware, a high-performance quantum computer
 simulator with emulation capabilities, and various compiler plug-ins.
 This allows users to
 
--  run quantum programs on the IBM Quantum Experience chip
+-  run quantum programs on the IBM Quantum Experience chip, AQT devices or AWS Braket service provided devices
 -  simulate quantum programs on classical computers
 -  emulate quantum programs at a higher level of abstraction (e.g.,
    mimicking the action of large oracles instead of compiling them to
@@ -134,6 +134,44 @@ To run a program on the AQT trapped ion quantum computer, choose the `AQTBackend
                      engine_list=compiler_engines)
 
 
+**Running a quantum program on a AWS Braket provided device**
+
+To run a program on some of the devices provided by the AWS Braket service,
+choose the `AWSBraketBackend`. The currend devices supported are Aspen-8 from Rigetti,
+IonQ from IonQ and the state vector simulator SV1:
+
+.. code-block:: python
+
+    from projectq.backends import AWSBraketBackend
+
+    creds = {
+        'AWS_ACCESS_KEY_ID': 'your_aws_access_key_id',
+        'AWS_SECRET_KEY': 'your_aws_secret_key',
+        }
+
+    s3_folder = ['S3Bucket', 'S3Directory']
+    device='IonQ'
+    eng = MainEngine(AWSBraketBackend(use_hardware=True, credentials=creds, s3_folder=s3_folder,
+                     num_runs=1024, verbose=False, device=device),
+                     engine_list=[])
+
+
+.. note::
+
+   In order to use the AWSBraketBackend, you need to install ProjectQ with the 'braket' extra requirement:
+
+   .. code-block:: bash
+
+       python3 -m pip install projectq[braket]
+
+   or
+
+   .. code-block:: bash
+
+       cd /path/to/projectq/source/code
+       python3 -m pip install -ve .[braket]
+
+
 **Classically simulate a quantum program**
 
 ProjectQ has a high-performance simulator which allows simulating up to about 30 qubits on a regular laptop. See the `simulator tutorial <https://github.com/ProjectQ-Framework/ProjectQ/blob/feature/update-readme/examples/simulator_tutorial.ipynb>`__ for more information. Using the emulation features of our simulator (fast classical shortcuts), one can easily emulate Shor's algorithm for problem sizes for which a quantum computer would require above 50 qubits, see our `example codes <http://projectq.readthedocs.io/en/latest/examples.html#shor-s-algorithm-for-factoring>`__.

docs/tutorials.rst

@@ -44,6 +44,14 @@ ProjectQ comes with a high-performance quantum simulator written in C++. Please
 .. note::
 	ProjectQ should be installed on each computer individually as the C++ simulator compilation creates binaries which are optimized for the specific hardware on which it is being installed (potentially using our AVX version and `-march=native`). Therefore, sharing the same ProjectQ installation across different hardware may cause some problems.
 
+**Install AWS Braket Backend requirement**
+
+AWS Braket Backend requires the use of the official AWS SDK for Python, Boto3. This is an extra requirement only needed if you plan to use the AWS Braket Backend. To install ProjectQ inluding this requirement you can include it in the installation instruction as
+
+.. code-block:: bash
+
+	python -m pip install --user projectq[braket]
+
 
 Detailed instructions and OS-specific hints
 -------------------------------------------

examples/awsbraket.ipynb

@@ -0,0 +1,210 @@
+{
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.10-final"
+  },
+  "orig_nbformat": 2,
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3.7.10 64-bit",
+   "metadata": {
+    "interpreter": {
+     "hash": "fd69f43f58546b570e94fd7eba7b65e6bcc7a5bbc4eab0408017d18902915d69"
+    }
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2,
+ "cells": [
+  {
+   "source": [
+    "# Running ProjectQ code on AWS Braket service provided devices\n",
+    "## Compiling code for AWS Braket Service\n",
+    "\n",
+    "In this tutorial we will see how to run code on some of the devices provided by the Amazon AWS Braket service. The AWS Braket devices supported are: the State Vector Simulator 'SV1', the Rigetti device 'Aspen-8' and the IonQ device 'IonQ'\n",
+    "\n",
+    "You need to have a valid AWS account, created a pair of access key/secret key, and have activated the braket service. As part of the activation of the service, a specific S3 bucket and folder associated to the service should be configured.\n",
+    "\n",
+    "First we need to do the required imports. That includes the mail compiler engine (MainEngine), the backend (AWSBraketBackend in this case) and the operations to be used in the cicuit"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from projectq import MainEngine\n",
+    "from projectq.backends import AWSBraketBackend\n",
+    "from projectq.ops import Measure, H, C, X, All\n"
+   ]
+  },
+  {
+   "source": [
+    "Prior to the instantiation of the backend we need to configure the credentials, the S3 storage folder and the device to be used (in the example the State Vector Simulator SV1)"
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "creds = {\n",
+    "    'AWS_ACCESS_KEY_ID': 'aws_access_key_id',\n",
+    "    'AWS_SECRET_KEY': 'aws_secret_key',\n",
+    "    } # replace with your Access key and Secret key\n",
+    "\n",
+    "s3_folder = ['S3Bucket', 'S3Directory'] # replace with your S3 bucket and directory\n",
+    "\n",
+    "device = 'SV1' # replace by the device you want to use"
+   ]
+  },
+  {
+   "source": [
+    "Next we instantiate the engine with the AWSBraketBackend including the credentials and S3 configuration. By setting the 'use_hardware' parameter to False we indicate the use of the Simulator. In addition we set the number of times we want to run the circuit and the interval in secons to ask for the results. For a complete list of parameters and descriptions, please check the documentation."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+       "eng = MainEngine(AWSBraketBackend(use_hardware=False,\n",
+       "                                  credentials=creds,\n",
+       "                                  s3_folder=s3_folder,\n",
+       "                                  num_runs=10,\n",
+       "                                  interval=10))"
+   ]
+  },
+  {
+   "source": [
+    "We can now allocate the required qubits and create the circuit to be run. With the last instruction we ask the backend to run the circuit."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Allocate the required qubits\n",
+    "qureg = eng.allocate_qureg(3)\n",
+    "\n",
+    "# Create the circuit. In this example a quantum teleportation algorithms that teleports the first qubit to the third one.\n",
+    "H | qureg[0]\n",
+    "H | qureg[1]\n",
+    "C(X) | (qureg[1], qureg[2])\n",
+    "C(X) | (qureg[0], qureg[1])\n",
+    "H | qureg[0]\n",
+    "C(X) | (qureg[1], qureg[2])\n",
+    "\n",
+    "# At the end we measure the qubits to get the results; should be all-0 or all-1\n",
+    "All(Measure) | qureg\n",
+    "\n",
+    "# And run the circuit\n",
+    "eng.flush()\n"
+   ]
+  },
+  {
+   "source": [
+    "The backend will automatically create the task and generate a unique identifier (the task Arn) that can be used to recover the status of the task and results later on.\n",
+    "\n",
+    "Once the circuit is executed the indicated number of times, the results are stored in the S3 folder configured previously and can be recovered to obtain the probabilities of each of the states."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Obtain and print the probabilies of the states\n",
+    "prob_dict = eng.backend.get_probabilities(qureg)\n",
+    "print(\"Probabilites for each of the results: \", prob_dict)"
+   ]
+  },
+  {
+   "source": [
+    "## Retrieve results form a previous execution\n",
+    "\n",
+    "We can retrieve the result later on (of this job or a previously executed one) using the task Arn provided when it was run. In addition, you have to remember the amount of qubits involved in the job and the order you used. The latter is required since we need to set up a mapping for the qubits when retrieving results of a previously executed job.\n",
+    "\n",
+    "To retrieve the results we need to configure the backend including the parameter 'retrieve_execution' set to the Task Arn of the job. To be able to get the probabilities of each state we need to configure the qubits and ask the backend to get the results."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Set the Task Arn of the job to be retrieved and instantiate the engine with the AWSBraketBackend\n",
+    "task_arn = 'your_task_arn' # replace with the actual TaskArn you want to use\n",
+    "\n",
+    "eng1 = MainEngine(AWSBraketBackend(retrieve_execution=task_arn, credentials=creds, num_retries=2, verbose=True))\n",
+    "\n",
+    "# Configure the qubits to get the states probabilies\n",
+    "qureg1 = eng1.allocate_qureg(3)\n",
+    "\n",
+    "# Ask the backend to retrieve the results\n",
+    "eng1.flush()\n",
+    "\n",
+    "# Obtain and print the probabilities of the states\n",
+    "prob_dict1 = eng1.backend.get_probabilities(qureg1)\n",
+    "print(\"Probabilities \", prob_dict1)\n"
+   ]
+  },
+  {
+   "source": [
+    "We can plot an histogram with the probabilities as well."
+   ],
+   "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "%matplotlib inline\n",
+    "from projectq.libs.hist import histogram\n",
+    "\n",
+    "histogram(eng1.backend, qureg1)\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ]
+}

projectq/backends/__init__.py

@@ -25,10 +25,12 @@
   circuit)
 * an interface to the IBM Quantum Experience chip (and simulator).
 * an interface to the AQT trapped ion system (and simulator).
+* an interface to the AWS Braket service decives (and simulators)
 """
 from ._printer import CommandPrinter
 from ._circuits import CircuitDrawer, CircuitDrawerMatplotlib
 from ._sim import Simulator, ClassicalSimulator
 from ._resource import ResourceCounter
 from ._ibm import IBMBackend
 from ._aqt import AQTBackend
+from ._awsbraket import AWSBraketBackend

projectq/backends/_awsbraket/__init__.py

@@ -0,0 +1,26 @@
+#   Copyright 2021 ProjectQ-Framework (www.projectq.ch)
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+try:
+    from ._awsbraket import AWSBraketBackend
+except ImportError:  # pragma: no cover
+    import warnings
+    warnings.warn("Failed to import one of the dependencies required to use "
+                  "the Amazon Braket Backend.\n"
+                  "Did you install ProjectQ using the [braket] extra? "
+                  "(python3 -m pip install projectq[braket])")
+
+    # Make sure that the symbol is defined
+    class AWSBraketBackend:
+        pass