We regularly publish Docker images that contain the Forest SDK pre-installed. They will also start up quilc and QVM servers upon container start.

Running the Image

To use the image, just run the following in a terminal:

docker run --rm -it rigetti/forest

You'll then be presented with an IPython prompt, where you can easily write and execute Quil programs.

Running Programs

Try running a simple Quil program against a QVM by pasting the following into the IPython prompt:

from pyquil import get_qc, Program
from pyquil.gates import H, CNOT, MEASURE
from pyquil.quilbase import Declare
​
program = Program(
    Declare("ro", "BIT", 2),
    H(0),
    CNOT(0, 1),
    MEASURE(0, ("ro", 0)),
    MEASURE(1, ("ro", 1)),
).wrap_in_numshots_loop(10)
​
qc = get_qc("2q-qvm")
​
qc.run(qc.compile(program)).readout_data.get("ro")

from pyquil import get_qc, Program
from pyquil.gates import H, CNOT, MEASURE
from pyquil.quilbase import Declare
​
program = Program(
    Declare("ro", "BIT", 2),
    H(0),
    CNOT(0, 1),
    MEASURE(0, ("ro", 0)),
    MEASURE(1, ("ro", 1)),
).wrap_in_numshots_loop(10)
​
qc = get_qc("2q-qvm")
​
qc.run(qc.compile(program))

If all goes well, you'll see results similar to the following:

array([[1, 1],
       [0, 0],
       [0, 0],
       [0, 0],
       [1, 1],
       [0, 0],
       [1, 1],
       [0, 0],
       [1, 1],
       [0, 0]])

Programs on Your Host Computer

While typing programs into the IPython prompt can be instructive, it's often more useful to run programs that you're working on from your host computer.

For example, if you have a program located on your host computer at ~/pyquil/example.py, you can run the program using the rigetti/forest image with the following command:

docker run --rm -it -v ~/pyquil:/root/pyquil rigetti/forest python /root/pyquil/example.py

Avoiding Container Restarts

If you don't want to have to restart the container each time you run a program, you can start the container into a terminal instead:

docker run --rm -it -v ~/.qcs:/root/.qcs -v ~/pyquil:/root/pyquil rigetti/forest bash

Then, each time you need to run a program, you can execute it with the python command:

python ~/pyquil/example.py

Using JupyterLab

If you prefer to work with programs as Jupyter notebooks located on your host computer, you can run the rigetti/forest image with the following command (assuming notebooks are located in ~/pyquil on your host computer):

docker run --rm -it -p 8888:8888 -v ~/pyquil:/root/pyquil rigetti/forest bash -c "pip install jupyterlab && jupyter lab --ip 0.0.0.0 --no-browser --allow-root /root/pyquil"

You should see a JupyterLab server start up and print out a URL of the form:

http://127.0.0.1:8888/lab?token=...

You can then paste that URL into a browser on your host computer and start creating notebooks!