Quantum simulation on GCP with Cirq and qsim

This tutorial demonstrates how to run Cirq on the Google Cloud Platform. It shows how to install Cirq within a Docker container on a GCE Virtual Machine and view the results. You will run the simulation in a Jupyter environment and interactively within the container. In this tutorial you will:

  • Create a Container Optimized VM
  • Run Docker container with Jupyter and qsim installed
  • Run a demo circuit

GCP setup


This tutorial uses billable components of Google Cloud Platform, including the Compute Engine. Use the Pricing Calculator to generate a cost estimate based on your projected usage.

Before you begin

These are the steps to follow to get started with this tutorial:

  • Creating a Cloud Platform project
  • Enabling billing for the project
  • Enable Google Compute Engine API

For this reference guide, you need a Google Cloud project. You can create a new one, or select a project you already created:

  1. Select or create a Google Cloud project on the project selector page.
  2. Enable billing for your project.

After finishing this tutorial, you can avoid continued billing by deleting the resources you created. See Clean up section below for details.

Create a GCE VM

Once you have a project enabled with a billing account, you will be able to create resources. The key resource required for this project is a Virtual Machine (VM) used to run the qsim quantum simulations.

Use the Cloud Console

Connect to the Cloud Console and make sure your current project is selected. Then click on Create for a new VM instance:


Build a Container Optimized VM

To create the VM use the steps in sequence below:

  • Change the name of the VM to be something meaningful like "qsim-1".
  • Choose a Region and Zone
  • Choose the machine family / series: N2
    • Quantum simulation requires powerful processors—the N2, N1, or C2 will work.
    • But if you have your own prefences, other machine types are available.



Finally, enable HTTP access and click Create.


Preparing your local system to connect to Colab

Google Colab allows you to write and execute Python in your browser, with:

  • Zero configuration required
  • Free access to GPUs
  • Easy sharing

This tutorial focuses on how to run simulations GCE VM your created above using Colab as the UI / frontend.

Install gcloud on your local machine

In order to connect your VM to Colab, you need to forward the default Jupyter port (8888) to your localhost. Port forwarding to a GCP VM requires that you have the Google Cloud Platform SDK installed on your local computer. This will give you access to the gcloud command. See the Installing Google Cloud SDK guide.

After installing, initialize the Google Cloud environment:

$ gcloud init

Respond to the prompts with your project ID and the zone where you created your VM. When completed, view the gcloud configuration:

$ gcloud config list

Output should look something like:

region = us-east4
zone = us-east4-c
account = wellhello@gargle.com
disable_usage_reporting = False
project = quantum-22222

Connect via port forward to your VM

You are now ready to connect to your VM through a port forward gcloud command. Detailed instructions can be found in the Colab local runtimes guide, but the following instructions are sufficient to succeed. Connect up with SSH with port 8888 forwarded to your local machine:

$ gcloud compute ssh [YOUR_INSTANCE_NAME] -- -L 8888:localhost:8888

You should now see the command line prompt from your VM:

wellhello@qsim-1 ~ $ 

Run the Jupyter / qsim container on your VM

At the command prompt you can now start a Docker container with all the required code to run simulations. Start the container:

$ docker run -v `pwd`:/homedir -p 8888:8888 gcr.io/quantum-builds/github.com/quantumlib/jupyter_qsim:latest

You should see several lines of output ending with lines like below. (If you get an error about permission denied you may need to run docker with sudo as described here).

To access the notebook, open this file in a browser:
Or copy and paste one of these URLs:

Copy the last URL in the output. Edit the URL to replace with localhost. Save this URL for the next step. This URL points to your local runtime, running as a Docker container on your VM.

Connect Colab to your local runtime

First, get a notebook up and running on Colab. Open the Get started with qsimcirq notebook in Colab.

If you are connect to Colab with a notebook visible, you can click Connect to get the UI:

Select Connect to local runtime. You will see the UI:

Pass the edited URL from the previous section, then click Connect:

You should now be able to run the cells in the notebook.

Large circuit

A large circuit is provided with 32 qubits and a depth of 14 gate operations. Open the Simulate large quantum circuit notebook in Colab.

This large circuit will not succeed if you attempt to run the default runtime. Ensure that you repeat the connection procedure to the local runtime.

Optional: Connect to Jupyter directly

Once you have port 8888 forwarded and the container running on your GCE VM, it is easy to connect directly to Jupyter without using Colab.

In the previous step, you copied a URL like below. It is easy to just copy that URL and paste it directly into a browser running on your local machine.

In the browser you should now see the Jupyter UI:


To see the notebooks, navigate to qsim > docs > tutorials. You will see:


Click on the qsimcirq.ipynb file. This will load the notebook.

You can now run these cells as you would in any notebook.


If you choose to modify the notebook, you can save it on the qsim-1 VM from File -> Save As, and saving to /homedir/mynotebook.ipynb. This will save in your home directory on your VM. If you intend to destroy the VM after this tutorial, either download the notebooks from the VM or save directly from your browser.


Run interactively

To run interactively within the container, you can open a second shell window to the VM as you did above, but without the port forwarding:

$ gcloud compute ssh [YOUR_VM_NAME]

Now, find the container ID with docker ps to see something like this:

$ docker ps

CONTAINER ID        IMAGE                                       COMMAND                  CREATED             STATUS              PORTS                    NAMES
8ab217d640a3        gcr.io/quantum-291919/jupyter_qsim:latest   "jupyter-notebook --…"   2 hours ago         Up 2 hours>8888/tcp   dazzling_lovelace

The CONTAINER_ID is a UID something like "8ab217d640a3". Now you can connect to the container:

$ docker exec -it [CONTAINER_ID] /bin/bash

Build the circuit

Run Python 3:

$ python3

To import the libraries and build the circuit, copy and paste following into the VM window.

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.

You should see the output as

(0, 0): ───X^0.5───

Run the circuit

Now to see what the circuit does when under qsim. Again, copy the following into your VM window:

simulator = qsimcirq.QSimSimulator()
result = simulator.simulate(circuit)

The output is:

measurements: (no measurements)
output vector: (0.5+0.5j)|0⟩ + (0.5-0.5j)|1⟩

You have successfully simulated a quantum circuit on Google Cloud Platform using a Docker container.

Running your own script

If you want to run a Python script, you can locate a file in the home directory on your VM, then run something like the following in the container shell:

$ python3 /homedir/myscript.py

Exit the container

Exit the container by typing ctrl-d twice. You will see the output like:

[root@79804d33f250 /]# exit

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:

Delete the VM

It is usually recommended to delete the entire project you created for this tutorial, but if you want to continue using the project, you can easily either STOP the VM or Delete it. Select the VM, the either select the STOP square, or the DELETE trash can.


Delete the project

The easiest way to eliminate billing is to delete the project you created for the tutorial.

Be aware that deleting a project has the following effects:

  • Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
  • Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple tutorials and quickstarts, reusing projects can help you avoid exceeding project quota limits.

  1. In the Cloud Console, got to the Manage Resources page.
  2. In the project list, select the project that you want to delete and then click Delete.
  3. In the dialog, type the project ID and then click Shut down to delete the project.