Quantum simulation using Cirq and qsim on Google Cloud


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. New Google Cloud users might be eligible for a free trial.

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

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the Compute Engine API.

    Enable the 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.

  1. In the Google Cloud console, go to the Compute Engine VM instances page.

    Go to VM instances

  2. To create a VM instance, click Create:

    The dialog for creating a VM instance in the Google Cloud console.

  3. On the New VM instance page, fill out the following options in sequence:

    1. For Name, enter a descriptive name—for example, qsim-1.
    2. For Region and Zone, select options from the drop-down lists.

      This tutorial uses us-east4 for the region and us-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.

    3. 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.

    4. 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:

      New VM machine settings include the instance name, region, and zone
selections, and the machine configuration.

    5. In the Boot disk section, click Change.

      1. In the Operating system drop-down list, select Container Optimized OS.

        Leave the other settings as their default values.

      2. Click Select.

        Boot disk is a new 10-GB standard disk.

    6. For Firewall, select Allow HTTP traffic and Allow HTTPS traffic.

  4. 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.

  1. Install the Google Cloud CLI, then initialize it by running the following command:

    gcloud init
  2. 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.

  3. 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 port 8888 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

  1. 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.

  2. Copy the last URL in the output, and then replace 127.0.0.1 with localhost.

    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:

  1. In a web browser, open the Get started with qsimcirq Colab notebook.

  2. After the notebook loads, click Connect, and then click Connect to local runtime:

    The Connect drop-down menu shows an option for connecting to the local runtime.

  3. 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:

    The Local connection settings dialog includes a field where you copy your saved URL.

    After you receive the following success message, you can run the cells in the notebook:

    Menu bar shows a success message.

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.

  1. 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.

  2. 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.

  1. 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:

    A list of items is shown on the Files tab.

  2. Go to qsim > docs > tutorials.

    The qsimcirq.ipynb notebook is displayed:

    The notebook file is an item on the Files tab.

  3. To load the qsimcirq.ipynb notebook, click the filename.

    You can run cells such as the following:

    Notebook code for computing the final state vector of a circuit.

    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:

      The Save As dialog.

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

  1. 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 uses qsim-1.

  2. 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.

  3. 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

  1. In the second local shell session that you opened in the preceding section, run Python 3:

    $ python3
    
  2. 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.

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  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.

Stop or delete the VM

To stop or delete the VM used in this tutorial, do the following:

  1. In the Google Cloud console, go to the Compute Engine VM instances page.

    Go to VM instances

  2. Select the VM that you want to stop or delete.

  3. 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.