:warning: As of 11/17/2022, D-Wave is no longer available on Amazon Braket and has transitioned to the AWS Marketplace. Therefore, information on this page may be outdated. Learn more.
The Amazon Braket Ocean Plugin is an open source library in Python that provides a framework that you can use to interact with Ocean tools on top of Amazon Braket.
Before you begin working with the Amazon Braket Ocean Plugin, make sure that you've installed or configured the following prerequisites.
Download and install Python 3.7.2 or greater from Python.org. If you are using Windows, choose Add Python to environment variables before you begin the installation.
Make sure that your AWS account is onboarded to Amazon Braket, as per the instructions in the README.
Download and install Ocean tools.
pip install dwave-ocean-sdk
The Amazon Braket Ocean Plugin can be installed with pip as follows:
pip install amazon-braket-ocean-plugin
You can also install from source by cloning this repository and running a pip install command in the root directory of the repository:
git clone https://github.com/aws/amazon-braket-ocean-plugin-python.git
cd amazon-braket-ocean-plugin-python
pip install .
You can check your currently installed version of amazon-braket-ocean-plugin
with pip show
:
pip show amazon-braket-ocean-plugin
or alternatively from within Python:
>>> from braket import ocean_plugin
>>> ocean_plugin.__version__
Detailed documentation, including the API reference, can be found on Read the Docs.
To generate the API Reference HTML in your local environment
First, you must have tox installed.
pip install tox
Then, you can run the following command with tox to generate the documentation:
tox -e docs
To view the generated documentation, open the following file in a browser:
BRAKET_OCEAN_PLUGIN_ROOT/build/documentation/html/index.html
This package provides samplers which use Braket solvers. These samplers extend abstract base classes provided in Ocean's dimod and thus have the same interfaces as other samplers in Ocean.
BraketSampler
is a structured sampler that uses Braket-formatted parameters and properties. For example, instead of answer_mode
, which is used for D-Wave QPU samplers, Braket uses resultFormat
instead.
Linked is a sample example of solving the minimum vertex cover problem using BraketSampler
.
BraketDWaveSampler
is a structured sampler that uses D-Wave-formatted parameters and properties. It is interchangeable with D-Wave's DWaveSampler
.
Linked is the same example as above of solving the minimum vertex cover problem. Only the parameter inputs to the solver have been changed to be D-Wave formatted (e.g. answer_mode
instead of resultFormat
).
These usage examples can be found as python scripts in the BRAKET_OCEAN_PLUGIN_ROOT/examples/
folder.
Tasks sent to QPUs don't always complete right away. To view task status, you can enable debugging logs. An example of how to enable these logs is included in the repo: BRAKET_OCEAN_PLUGIN_ROOT/examples/debug_*
. These examples enable task logging so that status updates are continuously printed to terminal after a quantum task is executed. The logs can also be configured to save to a file or output to another stream. You can use the debugging example to get information on the tasks you submit, such as the current status, so that you know when your task completes.
Make sure to install test dependencies first:
pip install -e "amazon-braket-ocean-plugin-python[test]"
To run the unit tests:
tox -e unit-tests
You can also pass in various pytest arguments to run selected tests:
tox -e unit-tests -- your-arguments
For more information, please see pytest usage.
To run linters and doc generators and unit tests:
tox
Set the AWS_PROFILE
, as instructed in the amazon-braket-sdk-python README.
export AWS_PROFILE=YOUR_PROFILE_NAME
Running the integration tests will create an S3 bucket in the same account as the AWS_PROFILE
with the following naming convention amazon-braket-ocean-plugin-integ-tests-{account_id}
.
Run the tests:
tox -e integ-tests
As with unit tests, you can also pass in various pytest arguments:
tox -e integ-tests -- your-arguments
This project is licensed under the Apache-2.0 License.