Get started with Quantum Computing Service

Quantum Computing Service enables researchers to run quantum programs on Google’s quantum processors. This notebook is a tutorial to get you started with the typical setup, using the open source Python framework Cirq, in the free cloud Jupyter notebook environment, Colaboratory.

Access is currently restricted to those in an approved group, and you must be in that group before running this tutorial.

You can find more about running this in colaboratory in the Colab documentation or in our cirq-specific guide to running in colab. You can download this colab from the GitHub repository.

Before you begin

  • First, decide which project you will use the Quantum Computing Services from. All of your quantum programs and results will live under a project which you specify when creating and running these programs using Quantum Engine. You can use an existing project or create a new project. Learn more about creating a project

  • Log in and agree to Terms of Service

  • Follow this link to **enable the Quantum Engine API** in your Google Cloud Platform project.

After the API is enabled, you should be redirected to the Quantum Engine console and it should look like the following screenshot.

Quantum Engine landing

Enter your project id into the input text box below. To find your project id, click on the project menu in the blue bar at the top of the console. This will open a menu that displays your project name (e.g. “My project”) and unique project id (e.g. my-project-1234). Enter the project id into the input below. (Help on finding your project id)

Find project id

Run the code in the next block (the one with the text box), which will prompt you to authenticate Google Cloud SDK to use your project. You can run the code by either clicking the play button (pointed by arrow below) or by selecting the block and pressing CTRL-ENTER. After running the block you will see a link which you should click. This will open a new browser window. Follow the authentication flow for this window. After you authenticate and allow access to your project, you will be given a string which you should enter into the text box that appears in the run area (and then press return). If you see “Authentication complete” you have done this step successfully. If this fails, make sure that you have cut and paste the string correctly (e.g. the clipboard button seems to not work for some browser/OS combinations).

Run code block below

[ ]:
# The Google Cloud Project id to use.
project_id = 'qe-playground' #@param {type:"string"}


def setup_auth():
  """Runs the user through the Colab OAuth process.

  Sets the local Application Default Credentials. For more information on on
  using Application Default Credentials see
  https://cloud.google.com/docs/authentication/production
  """
  from google.colab import auth
  auth.authenticate_user(clear_output=False)

print("Getting OAuth2 credentials.")
print("Press enter after entering the verification code.")
setup_auth()
print("Authentication complete.")
print("installing cirq")
!pip install cirq --quiet
Getting OAuth2 credentials.
Press enter after entering the verification code.
Go to the following link in your browser:

    https://accounts.google.com/o/oauth2/auth?client_id=32555940559.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=openid+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fappengine.admin+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcompute+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Faccounts.reauth+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive&code_challenge=7ckPGGeMO4VR06QLBmW1gbAGBU17P8D6F3AqB0ZRGc4&code_challenge_method=S256&access_type=offline&response_type=code&prompt=select_account


Enter verification code: ··········
Authentication complete.
installing cirq
     |████████████████████████████████| 1.4MB 4.5MB/s

Authentication details Double clicking on the project_id block above should expose the code that is run when you run this code block. This code uses colabtools auth module to ensure that “Application Default Credentials” are set and then creates a variable colab_auth which can be used in Cirq to authenticate your calls to Quantum Engine.

If you are going to run code outside of colab and want to authenticate, see the below section on running from the command-line.

Create a circuit

Now that you’ve enabled Quantum Engine and configured the notebook, let’s create a basic program with Cirq. After reviewing the code, run this block to run a circuit, and print a circuit diagram and results. To learn more, refer to the Intro to Cirq and Cirq documentation.

[ ]:
import cirq
import cirq.google as cg
import random
import string

# Define a qubit at an arbitrary grid location.
qubit = cirq.GridQubit(0, 0)

# Create a circuit (qubits start in the |0> state).
circuit = cirq.Circuit(
    cirq.X(qubit),                 # Square root of NOT.
    cirq.measure(qubit, key='result')  # Measurement.
)

print("Circuit:")
print(circuit)
Circuit:
(0, 0): ───X───M('result')───

Simulate the circuit using Cirq

Let’s quickly use Cirq to simulate the circuit above.

[ ]:
# Simulate the circuit, repeating 1000 times.
print("Simulating circuit using Cirq...\n")
results = cirq.sample(circuit, repetitions=1000)
print("Measurement results:")
print(results)
Simulating circuit using Cirq...

Measurement results:
result=1111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111

Run on quantum hardware

Approved users can access quantum hardware in two modes. First, all approved users have access to a processo in “open-swim” which is a first-in-first-out queue with fairness algorithm that balances jobs across users in the queue. Secondly, processors can be reserved in hourly blocks if the user is approved. You can learn more about the reservation system on the concepts page. We’ll use the processor pacific in this demo.

Create a Quantum Engine client

Interactions with hardware are facilitated by the Quantum Computing Service. A client must first be initialized with your Google Cloud project to perform these interactions.

[ ]:
# Create an Engine client.
engine = cirq.google.Engine(project_id=project_id)

View the processor’s topology

Each processor has a set of available qubits laid out on a grid with limited couplings between qubits. The device specification can be printed to inspect the topology of a processor.

[ ]:
processor = engine.get_processor('pacific')

# Print the device showing qubit connectivity for the Sycamore gateset.
device = processor.get_device([cg.SYC_GATESET])
print(device)
                                             (0, 5)───(0, 6)
                                             │        │
                                             │        │
                                             (1, 5)───(1, 6)───(1, 7)
                                             │        │        │
                                             │        │        │
                                    (2, 4)───(2, 5)───(2, 6)───(2, 7)───(2, 8)
                                             │        │        │        │
                                             │        │        │        │
                                             (3, 5)───(3, 6)───(3, 7)───(3, 8)───(3, 9)
                                             │        │        │
                                             │        │        │
         (4, 1)───(4, 2)            (4, 4)───(4, 5)───(4, 6)───(4, 7)
         │        │                 │        │        │        │
         │        │                 │        │        │        │
(5, 0)───(5, 1)───(5, 2)───(5, 3)───(5, 4)───(5, 5)───(5, 6)───(5, 7)
         │        │        │        │        │        │        │
         │        │        │        │        │        │        │
         (6, 1)───(6, 2)───(6, 3)───(6, 4)───(6, 5)───(6, 6)───(6, 7)
                  │        │        │        │        │
                  │        │        │        │        │
                  (7, 2)───(7, 3)───(7, 4)───(7, 5)───(7, 6)
                           │        │        │
                           │        │        │
                           (8, 3)───(8, 4)───(8, 5)
                                    │
                                    │
                                    (9, 4)

Note that the qubit that we used for the simulation above, (0, 0), does not exist on the hardware. Since the grid may change over time, we’ll programatically select a valid qubit by inspecting device.qubits. We then use the optimized_for_sycamore() function to remap the circuit description for our device; this function will also substitute gates to comply with the device’s gate set.

[ ]:
valid_qubit = device.qubits[0]

# Re-map qubits and gates for Sycamore hardware.
syc_circuit = cg.optimized_for_sycamore(
    circuit,
    new_device=device,
    qubit_map=lambda q: valid_qubit) # Constant fn since there's only one qubit.

print(syc_circuit)
(0, 5): ───PhXZ(a=-1,x=1,z=0)───M('result')───

Create a job on the Quantum Engine

Cirq circuits are represented in the Quantum Computing Service as Programs. To run a Program, you must create a Job that specifies details about the execution, e.g. the processor to use and the number of times to repeat the experiment. This enables a single circuit to be run multiple times in different configurations. For a one-off use, these steps can be done together by using the engine.run_sweep utility to create both a Program and a Job.

A new Job will be scheduled on the requested hardware as it becomes available. The execution of your Job will likely be completed within a few seconds and the results will be displayed below. The output will include a link to the console, where you can view the status and results of your jobs.

[ ]:
print("Uploading program and scheduling job on Quantum Engine...\n")

# Upload the program and submit jobs to run in one call.
job = engine.run_sweep(
    program=syc_circuit,
    repetitions=10000,
    processor_ids=[processor.processor_id],
    gate_set=cg.SYC_GATESET)

print("Scheduled. View the job at: https://console.cloud.google.com/quantum/"
      "programs/{}?&project={}".format(job.program_id,
                                                      project_id))

# Print out the results. This blocks until the results are returned.
results = [str(int(b)) for b in job.results()[0].measurements['result'][:, 0]]
print("Measurement results:\n")
print(''.join(results))
Uploading program and scheduling job on Quantum Engine...

Scheduled. View the job at: https://console.cloud.google.com/quantum/programs/prog-UEPDBU3CSSULX8IW200829?&project=quantum-cloud-client
Measurement results:

1111111111111111101111111111111111110111101111111111111111111111111111111111111111111111111111111111111111111111111111111101101111111111111111111111111111111111111111111111111110111111111111111111111111111111111111111110111111111111111111111111111111111111111111111111101111111111111111111111110111011111111111111111111111111111111111111111111111111111111111011111111111111111111111111111111111111101111111111111111111111111111111111111111111110111111111101111111111111111111111111111111111111101111101111111111111111011111111111111111111011111111111111111111111110111101111111111111110111111111111111111111111111101111111111111111111111111111111111111111111111111111111111111111111111111111111111011111111111101111111111111101111111111111011111101111111111110111111011111111111111111111101111111111111111111111111111110111111111111111111111111111111110111111111111111011011111111111111111111111111111111111111111101111111111111111111111111111111111110111111111111111111111111111111111111111111111111111111111110111111111111111111111111111111111111101111111111111111111110111111101111111111111111111111111111110111111111111111111111111111111111111111111111111111111110111111111111111111111111111111111101111111111111111111111111111111111111111111111111111111101111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111001111110011111111111111111111101111111111111111111111101011111111011010111111111111111111011110111111111111111111111111111011111111111111111011111011111111111111011111111111111111111111111111111111111111110110111111111111111111011111111111111111111111111111111111101111111111111111110111110111111101111111111111111101111111111111111110111111111111101111111111111110101111111111111111111111111111111111111111111111111111111001111111111111111111110111111111111111111111111111111110111011111111111111111111111111101111111111111111111111111111101111111110111110111111111111101111111111111111111111111111111101111111111111111111111111111110101111111111111111111111011111111111110111111111111111111111011111111111111111111111111110111111111111111111111111111111011111111111111111011111111111111111011111111110111111111111111111111011111111110111111111111111111111111111110011111111111111111111111111111111111111111101111111111111111111111111111111111101111111111111111111111111111111111111111111111010111111111111111111111111111111111111111111111111111111111111111111111111111111111101101111111111111111111111111111111111111111111111111110111111111111111111111111111111111111111111111111111111111111101111111101111111111111111111111111111110111111111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111011111111111111111111111111111111101111111111111111111111110111111111111011111111111011101110111111111111101111111111111101111111011111010111111111110111111111111111111111101011111111111111111111111111111111111011111111111111111101111111111111111110111111011111111110011111111111111111111111111111111111111111111111111111111111111111111111011111111111111111111111111111101111111111101111111111111111111011110111111111111111110111110111110111111111111111111111111111111111111111111111111111101111111111111111111111111111111111111101111111111011111111111111110111111111111111111111111111111111111111111111111101111111111111111111111111111111011111111111111111111111111110111111111111101001111111111111110111111111111111111111111111111111111111111111111111111101111111111111111111111111011111111111101111111111111111111111111111111111111111111111111111111110111111111011011111111111110111111111111111111111111111111111111111111111111111111111111101111111111111111111111111111111011111111111111111111111111111111110111111101111111111111111011111111111111111111111111111111111111111111111111111111111111111110111111111110111011111111111111111111111111111111111111111111111111111111111111110111111111111111111101111111111111111111111111111111111111111111111111111111111011101111111111111111111111111111111111111111111111111111111111111111011111111111111111111111111111111111111111111111111111011111100111111111101111111111111111011111111111111111111111111111111111111111111111111111111111111111111111111001101110111111111101111111111111110111111111111111111111111110111111111111111111111111111111111011111111111111111011111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111111111011111111111111111111011111111111111111111111111111111101111011111111111111111111111101111111111111111111111011111111111111111111110111111111111111111111111111111111111111111111111111111111111111111111111111111111111011111111111111111011111111111110111111111110101111111111101111111111111111111111111111111111111111111111111110111110111111110111111111111111111111111111101101111111111111111111111111111111111111111111011111111111111111111111111111111111111111111111111111011101111111101011111111111111011111011111111111111111110111011111111101111111111111111111111111111011111111111111111111111111111111111101111111111111110111111111111111111111101111111111111111111111110111111111111111011111111111111111111111111111111111111111111111111111111111111111111111111111111111111111001111111111111111111111111111111111111111111101111111111111111111111111111111111110101111111011111111111111111111111111111111111111111111111101111111111111111111111011111101111111111111011111111111111111111111111111111111111111111111111111111111111101111111111111111101111111111111111111011111110111111111111110111111111111111111111111111111011110111111111111111111011111111111111111111111111111111101111111111111110111111100110111111111111111111111111111111111111111111111111111111111111111101011111111111111111111110111111110111111111111111111111111111111111111111111111111110111111111111111111111011111111111111011111101111111111111111111111111111111111111111111111110111111111111111111111111111111111111111111111111111111111111111111101111111111111111111101111111111111111111111011111111101111111111111111111111111111111111111101111111010111111111111111111111111111111111111111101111111111111111111111011111111111111111111111111111111111111111111101111111111011111011111111111111111111111111111111111111111111110111111111101111111111111111111111111111111111111111111111111111111011111111111111111111111011111010111111111111111111111011111111111111111111111110111111111111111111111111111111111111111101111111111111100111111111011111111111111111111111101110111111111110111111111111111111111111111111111111111111111111111111111111111111111111111111111101111111111111111110111111111101111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111100111111111111111111111111111101011111111111111111111111111111111101111111111111111111111111111111110101111111111111111111111111110111111111111111111111111111111111011111111111111111111111111111110111111111111111111111111111111111111111010111111111111111111111111111011111111111111111111111111111011111111111111111111011111111111111111111111111111110111101111111111111111111111111111111111111111111111011111111111111111111111111111111111101111111111111111101110111111111111101111111111111111111111111111111111111111111111111111111111111110111111111111111101111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111001111111111111111111011111111111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111111111111111101111111111111111111111111111111111011111101111111111111111111111111111111111111111111111111111101111111100111011111111111111111111111011111111011111111111111111111011111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111111111111101111111111111111111111011111111111111111111101111011111111111111111111111110111111111111111111111111111111111111111111111011110111111101111111111111111111111111111111111111111111111111111111111111111110111111111111111111111111111111111111111111110111011111111111111111111111111101111111111111111111111111111111111111111111111111111111111111111111111111111111011111111111111111111111111111111111111111111111111111111011111111111011111111111111111111111111111111111111111111111111111111111111111111111111111111111101111111111111111111111111111111111111111101101111111111101111101110111011111111111111111111111111111111111111111111111111110111111111111111111111111111111111111111111111111101111111111111111111111111111011011111111111111111111111111111101110111111111101111111110111111111111111111101111111111111111111111111111111111111111111111011111111111111101111111111111111111111111110111011111011111111111011111111111110111111111111111111111111111111111111111111111111111011111111111111111111011111101101111111111011111111111111011111111111111111111111111111111111111111111110111101111011111111111011111111111111111111111111011111011111111111111111110111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111111111111111111111111111111111111111101111111111111111110111111111111111111111100111111111111111111111111111111111011111111111110111111111111111111111111011111111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111111111111111110111111111011111111111111111111111111111111111111111111111111111111111111111111111111011111111111111111111111111111111110111111111111111111111111111111111111101111110111111111111101111111011111011111111111111111111110111111111111111011111111111111011011111111110111111111111111111111111111101101111011111111111111111111111111111111111111111101111111111111111111111101111111110011110111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111110111111111111111111111101111111111111111111111111111111111111111111111111111111111111011111111111111111111111111011111111111111111111111111111111111101111111111111011111111111111111011101111111111

Running from the command line

If you are planning to access Quantum Computing Service from the command line, follow these instructions to get started. If you plan on executing all of your programs from a ipython notebook, you can skip this section.

We assume that your local machine is configured to run python 3.6 or greater.

Instructions for installing Python 3:

Setup authentication

In this quickstart we will authenticate using the gcloud command line cool. To do this, one must first install gcloud. Follow the instructions for this at https://cloud.google.com/sdk/install. If you are running on a corp desktop, gcloud should be installed. We will authenticate using Application Default Credentials. To do this simply run the following on your shell command line

gcloud auth application-default login

This will open up a browser window or give you a link to a webpage you can navigate to in order to go through an authentication flow. Complete this using your @google.com account. After this command is run, credentials will be stored on your local machine. If at any point you want to revoke these credentials you can run gcloud auth application-default revoke

We highly recommend that you setup a virtualenv for this installation to isolate your development stack from your overall system installations. Instructions for virtualenvs are at https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/ Make sure to setup the virtual env for python 3 and not python 2.

Write and run a short quantum program

Using your favorite IDE or editor, read and then paste the following hello_qubit program into a file called hello_qubit.py. Make sure to replace the ‘your-project-id’ string with the project id you created above.

[ ]:
import cirq

def example():
    """Hello qubit example run against a quantum processor."""

    # Define a qubit.
    qubit = cirq.GridQubit(5, 2)

    # Create a circuit (qubits start in the |0> state).
    circuit = cirq.Circuit(
        cirq.X(qubit)**0.5,                # Square root of NOT.
        cirq.measure(qubit, key='result')  # Measurement.
    )

    # Create an Engine object.  This uses the project id of your
    # Google cloud project.
    project_id = 'your-project-id'
    engine = cirq.google.Engine(project_id=project_id)

    print("Uploading program and scheduling job on Quantum Engine...\n")

    # Upload the program and submit jobs to run in one call.
    job = engine.run_sweep(
        program=circuit,
        repetitions=1000,
        processor_ids=['pacific'],
        gate_set=cirq.google.SYC_GATESET)

    print("Scheduled. View the job at: https://console.cloud.google.com/quantum/"
          f"programs/{job.program_id}/jobs/{job.job_id}"
          f"/overview?project={project_id}")

    # Print out the results. This blocks until the results are returned.
    results = [str(int(b)) for b in job.results()[0].measurements['result'][:, 0]]
    print("\nMeasurement results:")
    print(''.join(results))


if __name__ == '__main__':
    example()

You should then be able to run this program from your command line using:

python hello_qubit.py

The output should be something like:

Uploading program and scheduling job on Quantum Engine...

Scheduled. View the job at: https://console.cloud.google.com/quantum/programs/example-T5K9Y9/jobs/job-0?mods=quantum_ng2&project=quantum-cloud-client

Measurement results:
1010101010111011000011101010101011010011100111110001101101101011100011111010100100011000010101110010011000100001110000100010011100111101001101101010000000111101010100001001101110101010110000010011110101100000101111101000010000000100010111010101110001110101101100010001101111100110001001010000100000110110100000111111110011100101111000010110010101100010111111100010001100111011010101111011000110100001010000011100000100101010111110111010011010100011011111110110011101010001000101000011101000111000001001101000110000111111000111100001001000010101011111000111111010100001011001010011011000010110111010001011000001011110001010110100001101011101110011111100100101010011100010010001100101100001101010010011001010100011010010011000010010001010111101001000011000101111011111100111111111101001010010001010000101011101100100001101011100101010101110111001101000100101111101100000100010000101000011110110101001101100000000000111000000111011101101110000001110110001111011000100111111101110111111101001110110000110

Next steps