Installation and Getting Started¶
To make full use of the Rigetti Forest SDK, you will need pyQuil, the QVM, and the Quil Compiler. On this page, we will take you through the process of installing all three of these. We also step you through running a basic pyQuil program.
Note
If you’re running from a Rigetti-provisioned JupyterLab IDE, installation has been completed for you. Continue to Getting Started.
Upgrading or Installing pyQuil¶
pyQuil is our library for generating and executing Quil programs on the Rigetti Forest platform.
Before you install, we recommend that you activate a Python 3.7+ virtual environment. Then, install pyQuil using pip:
pip install pyquil
For those of you that already have pyQuil, you can upgrade with:
pip install --upgrade pyquil
If you would like to stay up to date with the latest changes and bug fixes, you can also opt to install pyQuil from the source here.
Note
pyQuil requires Python 3.7 or later.
Downloading the QVM and Compiler¶
The Forest 3.0 Downloadable SDK Preview currently contains:
The Quantum Virtual Machine (
qvm
) which allows high-performance simulation of Quil programsThe Quil Compiler (
quilc
) which allows compilation and optimization of Quil programs to native gate sets
The QVM and the compiler are packed as program binaries that are accessed through the command line. Both of them provide support for direct command-line interaction, as well as a server mode. The server mode is required for use with pyQuil.
Download the Forest SDK here, where you can find links for Windows, macOS, Linux (.deb), Linux (.rpm), and Linux (bare-bones).
All installation mechanisms, except the bare-bones package, require administrative privileges to install. To use the QVM and Quil Compiler from the bare-bones package, you will have to install the prerequisite dependencies on your own.
Note
You can also find the open source code for quilc and qvm on GitHub, where you can find instructions for compiling, installing, and contributing to the compiler and QVM.
Installing the QVM and Compiler on Windows¶
Download the Windows distribution by clicking on the appropriate link on the SDK download page.
Open the file forest-sdk.msi
by double clicking on it in your Downloads folder, and follow the system prompts.
Upon successful installation, one should be able to open a new terminal window and run the following two commands:
qvm --version
quilc --version
To uninstall the Forest SDK, search for “Add or remove programs” in the Windows search bar. Click on “Add or remove programs” and, in the resulting window, search for “Forest SDK for Windows” in the list of applications and click on “Uninstall” to remove it.
Installing the QVM and Compiler on macOS¶
Download the macOS distribution by clicking on the appropriate link on the SDK download page.
Mount the file forest-sdk.dmg
by double clicking on it in your Downloads folder. From there, open forest-sdk.pkg
by
double-clicking on it. Follow the installation instructions.
Upon successful installation, one should be able to open a new terminal window and run the following two commands:
qvm --version
quilc --version
To uninstall, delete the following files:
/usr/local/bin/qvm
/usr/local/bin/quilc
/usr/local/share/man/man1/qvm.1
/usr/local/share/man/man1/quilc.1
Installing the QVM and Compiler on Linux (deb)¶
Download the Debian distribution by clicking on the appropriate link on the SDK download page. Unpack the tarball and change to that directory
by doing (filling in <version>
appropriately):
tar -xf forest-sdk-linux-deb.tar.bz2
cd forest-sdk-<version>-linux-deb
From here, run the following command:
sudo ./forest-sdk-<version>-linux-deb.run
Upon successful installation, one should be able to run the following two commands:
qvm --version
quilc --version
To uninstall, type:
sudo apt remove forest-sdk
Installing the QVM and Compiler on Linux (rpm)¶
Download the RPM-based distribution by clicking on the appropriate link on the SDK download page. Unpack the tarball and change to that
directory by doing (filling in <version>
appropriately):
tar -xf forest-sdk-linux-rpm.tar.bz2
cd forest-sdk-<version>-linux-rpm
From here, run the following command:
sudo ./forest-sdk-<version>-linux-rpm.run
Upon successful installation, one should be able to run the following two commands:
qvm --version
quilc --version
To uninstall, type:
sudo rpm -e forest-sdk
# or
sudo yum uninstall forest-sdk
Installing the QVM and Compiler on Linux (bare-bones)¶
The bare-bones installation only contains the executable binaries and
manual pages, and doesn’t contain any of the requisite dynamic
libraries. As such, installation doesn’t require administrative or
sudo
privileges.
First, unpack the tarball and change to that directory by doing (filling in <version>
appropriately):
tar -xf forest-sdk-linux-barebones.tar.bz2
cd forest-sdk-<version>-linux-barebones
From here, run the following command:
./forest-sdk-<version>-linux-barebones.run
Upon successful installation, this will have created a new directory rigetti
in your home directory that contains all
of the binary and documentation artifacts.
This method of installation requires one, through whatever means, to install shared libraries for BLAS, LAPACK, and libffi. On a Debian-derivative system, this could be accomplished with
sudo apt-get install liblapack-dev libblas-dev libffi-dev libzmq3-dev
Or on any rhel-derivative systems (e.g. Amazon Linux) with
sudo yum install -y lapack-devel blas-devel epel-release
sudo yum install -y zeromq3-devel
To uninstall, remove the directory ~/rigetti
.
Getting Started¶
To get started using the SDK, you can either interact with the QVM and the compiler directly from the command line, or you can run them in server mode and use them with pyQuil. In this section, we’re going to explain how to do the latter.
For more information about directly interacting with the QVM and the compiler, refer to their respective manual pages.
After installation, you can read the manual pages by opening a new terminal window and typing man qvm
(for the QVM)
or man quilc
(for the compiler). Quit out of the manual page by typing q
.
Setting Up Server Mode for pyQuil¶
Note
This set up is only necessary to run pyQuil locally. If you’re running from your JupyterLab notebook, this has already been done for you.
It’s easy to start up local servers for the QVM and quilc on your laptop. You should have two terminal windows open
to run in the background. We recommend using a resource such as tmux
for running and managing multiple programs in one
terminal.
### CONSOLE 1
$ qvm -S
Welcome to the Rigetti QVM
(Configured with 10240 MiB of workspace and 8 workers.)
[2018-09-20 15:39:50] Starting server on port 5000.
### CONSOLE 2
$ quilc -S
... - Launching quilc.
... - Spawning server at (tcp://*:5555) .
That’s it! You’re all set up to run pyQuil locally. Your programs will make requests to these server endpoints to compile your Quil programs to native Quil, and to simulate those programs on the QVM.
NOTE: Prior to quilc version 1.10 there existed two methods for communicating with the quilc server: over HTTP by creating the server with the -S
flag, or over RPCQ by creating the server with the -R
flag. The HTTP server mode was deprecated in early 2019, and removed in mid 2019. The -S
and -R
flags now both start the RPCQ server.
Run Your First Program¶
Now that our local endpoints are up and running, we can start running pyQuil programs! We will run a simple program on the Quantum Virtual Machine (QVM).
The program we will create prepares a fully entangled state between two qubits, called a Bell State. This state is in an equal superposition between \(\ket{00}\) and \(\ket{11}\), meaning that it is equally likely that a measurement will result in measuring both qubits in the ground state or both qubits in the excited state.
To begin, start up python however you like. You can open a jupyter notebook (type jupyter notebook
in your terminal),
open an interactive python notebook in your terminal (with ipython3
), or simply launch python in your terminal
(type python3
). Recall that you need Python 3.6+ to use pyQuil.
Import a few things from pyQuil:
from pyquil import Program, get_qc
from pyquil.gates import *
from pyquil.quilbase import Declare
The Program
object allows us to build up a Quil program. get_qc()
connects us to a
QuantumComputer
object, which specifies what our program should run on (see: The Quantum Computer). We’ve also imported all (*
)
gates from the pyquil.gates
module, which allows us to add operations to our program (Programs and Gates). Declare
allows us to declare classical memory regions so that we can receive data from the QuantumComputer
.
Note
pyQuil also provides a handy function for you to ensure that a local qvm and quilc are currently running in
your environment. To make sure both are available you execute from pyquil.api import local_forest_runtime
and then use
local_forest_runtime()
. This will start qvm and quilc instances using subprocesses if they have not already been started.
You can also use it as a context manager as in the following example:
from pyquil import get_qc, Program
from pyquil.gates import CNOT, Z, MEASURE
from pyquil.api import local_forest_runtime
from pyquil.quilbase import Declare
prog = Program(
Declare("ro", "BIT", 2),
Z(0),
CNOT(0, 1),
MEASURE(0, ("ro", 0)),
MEASURE(1, ("ro", 1)),
).wrap_in_numshots_loop(10)
with local_forest_runtime():
qvm = get_qc('9q-square-qvm')
bitstrings = qvm.run(qvm.compile(prog)).readout_data.get("ro")
Next, let’s construct our Bell State.
# construct a Bell State program
p = Program(
Declare("ro", "BIT", 2),
H(0),
CNOT(0, 1),
MEASURE(0, ("ro", 0)),
MEASURE(1, ("ro", 1)),
).wrap_in_numshots_loop(10)
We’ve accomplished this by driving qubit 0 into a superposition state (that’s what the “H” gate does), and then creating an entangled state between qubits 0 and 1 (that’s what the “CNOT” gate does). Finally, we’ll want to run our program:
# run the program on a QVM
qc = get_qc('9q-square-qvm')
result = qc.run(qc.compile(p)).readout_data.get("ro")
print(result[0])
print(result[1])
Compare the two arrays of measurement results. The results will be correlated between the qubits and random from shot to shot.
The qc
is a simulated quantum computer. We’ve told our QVM to run the program specified above ten times and return
the results to us.
The calls to compile
and run
will make a request to the two servers we started up in the previous section:
first, to the quilc
server instance to compile the Quil program into native Quil, and then to the qvm
server
instance to simulate and return measurement results of the program 10 times. If you open up the terminal windows where
your servers are running, you should see output printed to the console regarding the requests you just made.
In the following sections, we’ll cover gates, program construction & execution, and go into detail about our Quantum Virtual Machine, our QPUs, noise models and more. Let’s start with the Programs and Gates.