Cirq Google Plugin

Common errors

• ModuleNotFoundError: No module named 'cirq_rigetti'

  cause The `cirq-rigetti` subpackage was removed starting from cirq-google v1.6.0.
  fix If your code explicitly uses `cirq_rigetti`, you need to downgrade your cirq-google installation to version 1.5.0 or earlier (e.g., `pip install cirq-google==1.5.0`). Alternatively, refactor your code to use the standalone `pyquil` library.

• ModuleNotFoundError: No module named 'cirq_ft'

  cause The `cirq-ft` package was removed from `cirq` and `cirq-google` starting from v1.4.0, as its functionality moved to the `Qualtran` library.
  fix If your code depends on `cirq_ft`, you need to install and use the `Qualtran` library directly from its GitHub repository (`https://github.com/quantumlib/Qualtran.git`). Alternatively, downgrade your `cirq-google` installation to `cirq-google<1.4.0` if you need the old `cirq-ft` functionality.

• RuntimeError: Python version must be >= 3.11.0

  cause You are trying to install or run `cirq-google` (version 1.6.0 or newer) with an unsupported Python version (e.g., 3.10 or older).
  fix Upgrade your Python environment to version 3.11 or later. For example, create a new virtual environment with `python3.11 -m venv .venv` and activate it.

• cirq_google.engine.calibration.engine_client.QuantumEngineError: Could not find or validate client credentials.

  cause The Cirq Google client failed to authenticate with the Google Quantum Engine. This means Google Cloud credentials are not properly set up or are expired.
  fix Ensure you are logged into Google Cloud via `gcloud auth application-default login` in your terminal, or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to a valid service account key file. Also, verify that the specified GCP project ID is correct and has the Quantum Engine API enabled.

Warnings

• breaking Cirq-Rigetti subpackage has been removed. If your project depends on `cirq-rigetti`, you must use an older version of Cirq (e.g., `cirq-rigetti-1.5.0`) or install `cirq-rigetti` explicitly if available.
  Fix: For new projects, avoid `cirq-rigetti`. For legacy code, pin `cirq-rigetti==1.5.0` and `cirq<1.6.0` or update your code to use the standalone `pyquil` library if applicable. `cirq-rigetti` was deprecated in v1.5.0 and removed in v1.6.0.
• breaking The minimum required Python version has been increased to 3.11.0. Older Python versions (e.g., 3.10 or earlier) are no longer supported.
  Fix: Upgrade your Python environment to 3.11.0 or higher. For example, using `pyenv install 3.11.8` and `pyenv local 3.11.8` or `conda install python=3.11`.
• breaking The `cirq-ft` package was removed. Its functionality has moved to the `Qualtran` repository.
  Fix: For fault-tolerant quantum algorithm resource estimation, use the `Qualtran` library directly from `https://github.com/quantumlib/Qualtran.git`. `cirq-ft` was deprecated in v1.3.0 and removed in v1.4.0.
• gotcha Authentication to Google Quantum Engine requires setting up Google Cloud credentials. Without proper authentication, `cirq_google.QuantumEngine` initialization or usage will fail.
  Fix: Run `gcloud auth application-default login` in your terminal, or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account key JSON file. Ensure your GCP project has the Quantum Engine API enabled.

Install

• pip install cirq cirq-google Install Cirq Google

Imports

• QuantumEngine

  from cirq_google import QuantumEngine

  The primary entry point for interacting with Google's Quantum Engine.
• Sycamore

  from cirq_google.devices import Sycamore

  Example of importing a specific Google quantum device model.

Quickstart

This quickstart demonstrates how to initialize the `QuantumEngine` client and run a simple Cirq circuit. For actual remote execution, ensure your Google Cloud environment is authenticated and `GOOGLE_CLOUD_PROJECT` (or a hardcoded project ID) is correctly configured. The example includes a fallback to a local Cirq simulator for immediate runnability without a full GCP setup.

import cirq
import cirq_google
import os

# Replace with your Google Cloud Project ID (e.g., 'your-project-id')
# For local testing, any string can be used, but for actual hardware access,
# it must be a valid GCP project ID with Quantum Engine API enabled.
PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT", "gcp-project-for-cirq-testing")

try:
    # Initialize the QuantumEngine client
    # This assumes you have authenticated via 'gcloud auth application-default login'
    # or set the GOOGLE_APPLICATION_CREDENTIALS environment variable.
    print(f"Attempting to initialize QuantumEngine for project: {PROJECT_ID}")
    engine = cirq_google.QuantumEngine(project_id=PROJECT_ID)
    
    # For quickstart, we'll try to use a local simulator
    # For actual hardware/remote simulator usage, you would use:
    # processor = engine.get_processor('willow_pink') # Example processor
    # job = engine.run_circuit(program=circuit, processor_ids=[processor.name], repetitions=10)
    # results = job.results()

    # Define a simple circuit
    qubit = cirq.GridQubit(0, 0)
    circuit = cirq.Circuit(
        cirq.H(qubit),
        cirq.measure(qubit, key='m')
    )

    # Run the circuit on a local Cirq simulator for quick demonstration
    print("Running circuit on local Cirq simulator...")
    simulator = cirq.Simulator()
    results = simulator.run(circuit, repetitions=10)
    print("Local simulation results:")
    print(results)

except Exception as e:
    print(f"Could not initialize QuantumEngine or connect to remote resources ({e}).")
    print("Falling back to local Cirq simulator for demonstration.")
    
    # Define a simple circuit
    qubit = cirq.GridQubit(0, 0)
    circuit = cirq.Circuit(
        cirq.H(qubit),
        cirq.measure(qubit, key='m')
    )

    # Run the circuit on a local Cirq simulator
    simulator = cirq.Simulator()
    results = simulator.run(circuit, repetitions=10)
    print("Local simulation results (fallback):")
    print(results)