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.

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, we provide the requirements for the tutorials as a convenient extras_require extension to pyQuil's setup.py file. Thus, run the following command in your Python environment to install all the necessary requirements:

pip install "pyquil[tutorials]"

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

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. The only caveat to this is that, if you add a notebook that depends on a third-party library that 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 the tutorials entry of the extras_require section in pyQuil's setup.py file, and wait for the changes to take effect in the following release.

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!