Interactive tutorial notebooks for pyQuil and Forest

This is a Binder repository containing tutorial notebooks for learning about pyQuil and the Forest SDK (quilc and the QVM). If you'd like to add a notebook, or change an existing one, make a pull request! And, to run the existing notebooks in a preconfigured environment on Binder, click the badge above!

Alternatively, you can run the image locally with the following command (replacing PORT with the localhost port you'd like to run the notebook server on):

docker run -p PORT:8888 rigetti/forest-tutorials

This will start the container, and somewhere in the terminal output it will print a URL that looks something like the following, but with TOKEN replaced with a long string of letters and numbers:

http://127.0.0.1:8888/?token=TOKEN

Copy paste the above URL into your browser, replacing 8888 with PORT. This will bring up the JupyterLab interface.

Running the notebooks without using Docker

We recommend using the Binder link above, or following the Docker-based instructions, if all you want to do is run the notebooks. This is because it requires no setup on your end (except for maybe installing Docker). However, if you'd like to run the notebooks locally without Docker, or if you'd like to make a pull request and contribute your own tutorial, you'll have to set up a Python environment with the necessary requirements installed. Normally, these are defined in a requirements.txt file, but adding one to this repo would cause Binder to use that for its configuration instead of the Dockerfile.

Thus, run the following command in your Python environment to install all the necessary requirements:

pip install pyquil jupyterlab matplotlib pandas forest-benchmarking

Then, assuming you've cloned this repository and you're in its top-level directory, running jupyter lab should be all you need to get started!

Contributing your own tutorial notebook

As mentioned above, if you'd like to contribute your own tutorial, or improve an existing one, you can make a pull request to this repository. If you add a notebook that depends on a third-party library and is not currently installed in the rigetti/forest-notebook Docker image (see the next section for more info), you will have to add the requirement to this document.

Building your own Forest-backed Binder repository

This Binder repository is built using the rigetti/forest-notebook Docker image, which comes with pyQuil installed, as well as quilc and QVM servers running in the background. It additionally has the forest-benchmarking library installed, along with some useful Python packages for data analysis and visualization. You can create your own Binder repository from this image by following the directions at the bottom of the README of the rigetti/forest-notebook repository!