This tutorial demonstrates how to simulate a quantum circuit by using Cirq and qsim on Google Cloud.
In this tutorial, you learn how to install Cirq and qsim in a Docker container on a Compute Engine virtual machine (VM) instance and view the results. You then run simulations of a quantum circuit in a Project Jupyter environment and interactively in the container. You also learn how to enable Colaboratory (Colab) as a notebook platform.
A fully capable quantum computer will not be generally available for several years. However, quantum circuit simulation is a viable alternative. This tutorial shows how to obtain the computing resources that are required to simulate a large quantum circuit.
The tutorial is for quantum simulation practitioners. It assumes you're familiar with the fundamentals of quantum computing and the simulation of quantum circuits, and with the limitations imposed by the memory requirements of large quantum circuits.
Explaining the concepts of quantum computing is beyond the scope of this tutorial. Excellent resources on that subject include the Cirq section of Google's Quantum AI website and the textbook Quantum Computation and Quantum Information by Michael A. Nielsen and Isaac L. Chuang.
Objectives
- Create a container-optimized VM.
- Provide a basic integration to the Colab notebook platform.
- Run simulations in a Docker container that has Jupyter and qsim installed.
- Run a sample circuit.
Costs
In this document, you use the following billable components of Google Cloud:
To generate a cost estimate based on your projected usage,
use the pricing calculator.
When you finish the tasks that are described in this document, you can avoid continued billing by deleting the resources that you created. For more information, see Clean up.
Before you begin
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Compute Engine API.
Creating a Compute Engine VM instance
In the following steps, you create a container-optimized VM instance that you use to run the qsim quantum simulations.
In the Google Cloud console, go to the Compute Engine VM instances page.
To create a VM instance, click Create:
On the New VM instance page, fill out the following options in sequence:
- For Name, enter a descriptive name—for example,
qsim-1
. For Region and Zone, select options from the drop-down lists.
This tutorial uses
us-east4
for the region andus-east4-c
for the zone. Although your selection isn't important for this tutorial, you might account for latency and availability. For more information, see Available regions and zones.For Machine configuration, click General purpose, and then in the Series drop-down list, select N2.
Quantum simulation requires powerful processors such as the N2, N1, and C2 processors. If you prefer another machine type, other options are available.
For Machine type, select
n2-standard-16
.The
n2-standard-16
machine type has 16 vCPUs and 64 GB of memory.At this point, the machine settings for this tutorial look similar to the following:
In the Boot disk section, click Change.
In the Operating system drop-down list, select Container Optimized OS.
Leave the other settings as their default values.
Click Select.
For Firewall, select Allow HTTP traffic and Allow HTTPS traffic.
- For Name, enter a descriptive name—for example,
Click Create.
Connecting your VM to Colab
This tutorial focuses on how to run simulations on your Compute Engine VM by using Colab as your frontend interface. Colab lets you write and run Python code in your web browser. Colab has several benefits:
- It requires no configuration.
- It offers free access to GPUs.
- It lets you share Jupyter notebooks while enabling all the security-related features of Google Google Drive.
At this point in the tutorial, you created a VM with sufficient resources to run your quantum simulation environment. To access this VM from Colab, you need to create a security-enhanced connection, which the following sections describe.
Activate gcloud
To connect your VM to Colab, you need to forward the default
Jupyter port (8888
) to your localhost.
Port forwarding
to a Google Cloud VM requires that you have the Google Cloud CLI installed on
your local computer. The gcloud CLI lets you access the Google Cloud CLI.
For more information, see the guide for
installing the gcloud CLI.
In the following steps, you initialize the environment on your local computer to enable port forwarding from a VM instance on Google Cloud to your local machine. You run these commands from a terminal window on your local machine.
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
In your local terminal window, set the project properties:
$ gcloud init
When you're prompted, enter the name of your Google Cloud project and the zone where you created your VM.
View the
gcloud
configuration:$ gcloud config list
The output is similar to the following:
region = us-east4 zone = us-east4-c [core] account = wellhello@gargle.com disable_usage_reporting = False project = quantum-22222
Connect your local machine to your VM through port forwarding
The next step is to connect to your VM through port forwarding by using a
gcloud
command.
In your local terminal window, use the
gcloud
SSH command to connect to your VM with port8888
forwarded to your local machine:$ gcloud compute ssh INSTANCE_NAME -- -L 8888:localhost:8888
Replace
INSTANCE_NAME
with the name of your VM instance that you created for this tutorial.The command prompt from your VM is displayed:
wellhello@qsim-1 ~ $
For detailed instructions on how to connect Colab to a VM through port forwarding, see the Colab local runtimes guide.
Running simulations in your Docker container
At this point in the tutorial, you can run simulations in your Docker container.
Run the container that has Jupyter and qsim installed
At the command prompt, start the container:
$ docker run -v `pwd`:/HOME_DIRECTORY -p 8888:8888 gcr.io/quantum-builds/github.com/quantumlib/jupyter_qsim:latest
Replace
HOME_DIRECTORY
with the home directory of your VM instance—for example,homedir
.The output ends with lines similar to the following:
... To access the notebook, open this file in a browser: file:///root/.local/share/jupyter/runtime/nbserver-1-open.html Or copy and paste one of these URLs: http://e1f7a7cca9fa:8888/?token=aa16e1b6d3f51c58928037d34cc6854dac47347dd4c0eae5 or http://127.0.0.1:8888/?token=aa16e1b6d3f51c58928037d34cc6854dac47347dd4c0eae5
If you get an error that permission is denied, you might need to run Docker with the
sudo
command.Copy the last URL in the output, and then replace
127.0.0.1
withlocalhost
.Save this revised URL for steps that come later in this tutorial. This URL points to your local runtime, which is running as a Docker container on your VM.
Connect Colab to your local runtime
At this point, you have a VM running a Docker container with a Jupyter server.
The Jupyter port (8888
) is forwarded to your local machine. The final step is
to connect Colab to the local 8888
port as if the Jupyter
runtime was on your local machine.
In the following steps, you get a notebook running in Colab, with the runtime hosted on your container VM:
In a web browser, open the Get started with qsimcirq Colab notebook.
After the notebook loads, click Connect, and then click Connect to local runtime:
In the Local connection settings dialog, paste the URL that you saved in the preceding section into the Backend URL field, and then click Connect:
After you receive the following success message, you can run the cells in the notebook:
Simulate a large quantum circuit
This tutorial provides a large circuit as a simulation example. The circuit has 32 qubits and a depth of 14 gate operations.
Before you simulate the circuit, make sure you followed the steps to connect Colab to your local runtime. If you use the default runtime, the circuit fails.
In Colab, open the Simulate large quantum circuit notebook.
The notebook contains guidance for simulating the circuit.
Connecting to Jupyter directly
If you prefer not to use Colab to simulate the circuit, you can use the Jupyter server on your VM.
After you forward port 8888
and start the container on your
Compute Engine VM, you can connect directly to Jupyter without using
Colab. This approach doesn't give you access to some convenient
features in Colab. However, it can be helpful for some use
cases—for example, if you're restricted from using Drive
to store code.
In a web browser on your local machine, paste the URL that you copied when you connected Colab to your local runtime.
The URL looks similar to the following:
http://127.0.0.1:8888/?token=7191178ae9aa4ebe1698b07bb67dea1d289cfd0e0b960373
The Jupyter interface is displayed:
Go to qsim > docs > tutorials.
The
qsimcirq.ipynb
notebook is displayed:To load the
qsimcirq.ipynb
notebook, click the filename.You can run cells such as the following:
If you want to save and modify the notebook, you can do the following:
- If you plan to keep the VM that you created for this tutorial, then you can save the notebook to your VM. Click File > Save As, and then save the file to the home directory of your VM.
If you plan to delete your VM, you can download the notebook from your VM or save it directly from your web browser:
Running a sample circuit interactively
If you prefer not to use a notebook environment for your simulation, you can interact directly with the Python interpreter that's running in your Docker container. In the following sections, you connect to the container, and then you build and simulate a virtual quantum circuit.
Connect to your Docker container
In your local terminal window, open a second shell session to your VM:
$ gcloud compute ssh INSTANCE_NAME
Replace
INSTANCE_NAME
with the name of the VM that you created for this tutorial. This tutorial usesqsim-1
.Find the container ID:
$ docker ps
The output is similar to the following:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8ab217d640a3 gcr.io/quantum-291919/jupyter_qsim:latest "jupyter-notebook --…" 2 hours ago Up 2 hours 0.0.0.0:8888->8888/tcp dazzling_lovelace
The container ID is a UID that looks similar to
8ab217d640a3
. Copy the ID, which you need for the next step.Connect to the container:
$ docker exec -it CONTAINER_ID /bin/bash
Replace
CONTAINER_ID
with the value that you copied in the preceding step.
Build the circuit
In the second local shell session that you opened in the preceding section, run Python 3:
$ python3
In the VM window, import the Cirq and qsim libraries and build the circuit:
import cirq import qsimcirq qubit = cirq.GridQubit(0, 0) # Pick a qubit. # Create a circuit circuit = cirq.Circuit( cirq.X(qubit)**0.5, # Square root of NOT. ) print("Circuit:") print(circuit)
The output is the following:
(0, 0): ───X^0.5───
Run the circuit
The following step demonstrates what the circuit does when you use qsim for the simulation:
In your VM terminal window, run the simulation:
simulator = qsimcirq.QSimSimulator() result = simulator.simulate(circuit) print("Result:") print(result)
The output is the following:
measurements: (no measurements) output vector: (0.5+0.5j)|0⟩ + (0.5-0.5j)|1⟩
Exit the container
To exit the container, press Control+D twice.
The output is similar to the following:
[root@79804d33f250 /]# exit
Clean up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, do the following:
- Delete the project.
- Stop or delete the VM.
Delete the project
Unless you want to continue using the Google Cloud project that you created for this tutorial, we recommend deleting the project.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Stop or delete the VM
To stop or delete the VM used in this tutorial, do the following:
In the Google Cloud console, go to the Compute Engine VM instances page.
Select the VM that you want to stop or delete.
Do one of the following:
- To stop the VM, click Stop.
- To delete the VM, click Delete.
What's next
- Explore reference architectures, diagrams, and best practices about Google Cloud. Take a look at our Cloud Architecture Center.