DOCSEARCHbyAlgolia
Submit Docs

Cirq Documentation

repository·main·Indexed 26 days ago

https://github.com/quantumlib/cirq

A Python package for writing, manipulating, and running quantum circuits on simulators and Noisy Intermediate-Scale Quantum (NISQ) hardware. Includes core functionality via cirq-core and specialized modules for hardware interfaces such as cirq-google, cirq-ionq, cirq-aqt, and cirq-pasqal, as well as cirq-web for creating web-based visualizations.

Tokens
57.9K
Snippets
179
Records
295
Agent score
90%

What's inside Cirq

  1. Explore Cirq Integrations

    main

    Cirq integrates with various open-source tools depending on your use case:

    InterestSoftware to explore
    Quantum algorithms / FTQC[Qualtran]
    Large circuits / high-performance simulation[qsim]
    Large-scale Clifford operations / QEC[Stim]
    Chemistry / Material science[OpenFermion], [OpenFermion-FQE], [OpenFermion-PySCF], [OpenFermion-Psi4]
    Quantum machine learning (QML)[TensorFlow Quantum]
    Real experiments[ReCirq]

  2. Access Google quantum processor device specifications

    main

    Google quantum processor specifications are provided as snapshots of DeviceSpecification proto messages. These are defined in cirq_google/api/v2/device.proto.

    To work with Google devices in Cirq, you can use these specification files. Files suffixed with _for_grid_device are equivalent representations of the standard proto files but use the new DeviceSpecification format, which is specifically parsed into cirq_google.GridDevice objects.

  3. Understand the QuantumEngineServiceTransport inheritance structure

    main

    The QuantumEngineServiceTransport serves as the Abstract Base Class (ABC) for all transport implementations in the quantum_engine_service. Depending on your requirements for synchronization and protocol, you should use one of the following implementations:

    • Sync gRPC: Use QuantumEngineServiceGrpcTransport (defined in grpc.py).
    • Async gRPC: Use QuantumEngineServiceGrpcAsyncIOTransport (defined in grpc_asyncio.py).
    • Sync REST: Use QuantumEngineServiceRestTransport (defined in rest.py). This implementation uses METHOD inner classes derived from the private _BaseMETHOD classes.

    Note that _BaseQuantumEngineServiceRestTransport is a private base class for REST transports and should not be used directly by end-users.

  4. Fork and sync the Cirq repository

    main

    To contribute to Cirq, fork the repository on GitHub, clone your fork, and add the original repository as an upstream remote to stay in sync with changes from the main repository.

    # 1. Clone your fork
git clone https://github.com/USERNAME/Cirq.git
cd Cirq

# 2. Add the upstream remote
git remote add upstream https://github.com/quantumlib/Cirq.git

# 3. Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

  5. Use Virtual Z gates for zero-duration rotations

    main
    Rotation around the Z axis is handled via compilation rather than hardware operations. Adding cirq.Z or cirq.ZPowGate gates will generally add zero duration to the circuit. The compiler automatically commutes these rotations through the circuit until a non-commuting gate is encountered.

  6. Get started with IonQ via Cirq

    main

    To use IonQ quantum computers through Cirq, follow these resources:

    1. Access and authentication: Learn how to obtain access to IonQ devices.
    2. Getting started guide: Follow the tutorial to run your first circuits on IonQ hardware.

    For general Cirq usage, refer to the main Cirq documentation site.

  7. Configure User Access and IAM permissions

    main

    Access to the Quantum Computing Service requires two levels of authorization for every user (email address):

    1. IAM Permissions: Each user must be associated with the Google Cloud Project and granted the appropriate IAM permissions within that project.
    2. Approved List: Each user must be added to an approved list to access the Quantum Computing Service.

    To add new users, submit their email addresses to your Google sponsor.

  8. Run all Cirq benchmarks including slow tests

    main

    Some benchmarks are marked with the slow marker (typically for larger parametrized benchmarks) and are deselected by default. To include these in your run, add the --enable-slow-tests flag.

    pytest -p no:randomly --override-ini="python_files=*_perf.py" \
    --benchmark-enable --enable-slow-tests ./benchmarks

  9. Find suitable issues for contribution

    main

    If you are looking to contribute to Cirq, look for these specific labels:

    • good first issue: Small, self-contained issues requiring level/beginner skills and complexity/low to complexity/medium.
    • good for learning: Small, self-contained issues requiring level/advanced skills and complexity/low to help build deep understanding.
    • good part time project: Issues requiring level/advanced skills and complexity/medium that may take a few months.
    • help wanted: High-priority or specific tasks that currently have no assignee.

  10. Structure a new Cirq visualization

    main

    New TypeScript visualizations should follow the structure used by the Bloch sphere example. Create a root folder within src/ named after your visualization. The structure should include:

    • Root folder: (e.g., src/my_viz/) containing all files for the visualization.
    • components/ directory: Contains classes for individual visualization components (e.g., Axes, Text).
    • assets/ directory: Contains necessary assets like fonts or images.
    • Main class: A class within the root folder that orchestrates the components.
    • main.ts: The entry point containing functions to receive input data, send output to the environment (notebook/HTML), and combine visualization aspects.

    Note: You must add your main.ts as an entry point in webpack.config.js to enable bundling.

    module.exports = {
  entry: {
    bloch_sphere: './src/bloch_sphere/main.ts',
    // ...
    YOUR_VIZ_NAME: './src/YOUR_VIZ_NAME/main.ts',
  },
  // ...
};

  11. Implement a standard plot method for classes

    main

    When implementing a plot method for a class in Cirq, follow these guidelines to ensure compatibility with interactive sessions (Jupyter, Colab) and automated tests:

    1. Interactive Mode (Default): If no ax argument is provided, the method should create a new figure, plot the data, call fig.show(), and return the ax instance. This allows users to see the plot immediately in interactive environments.
    2. Memory Mode: If an ax argument is provided, the method should plot onto that specific instance without calling fig.show(). This is essential for composing complex plots or running unit tests without triggering pop-up windows.
    3. Customizability: Always return the ax (or a list of ax objects) so the user can apply further customizations (labels, titles, styles) after the method call.
    4. Avoid plt.show(): Use fig.show() instead of plt.show() inside the method. Using plt.show() can prevent subsequent customizations on the returned ax from being visible.
    from typing import Any
import matplotlib.pyplot as plt

class Foo:
    def plot(self, ax: plt.Axes | None = None, **plot_kwargs: Any) -> plt.Axes:
        show_plot = not ax
        if ax is None:
            fig, ax = plt.subplots(1, 1)
        
        # Perform plotting logic using ax
        # ax.plot(...)
        
        if show_plot:
            fig.show()
        return ax

  12. Install cirq-ionq

    main

    Install the cirq-ionq module to enable running Cirq quantum algorithms on IonQ quantum computers. Installing this module automatically installs cirq-core and other necessary dependencies.

    To install the stable version:

    pip install cirq-ionq

    To install the latest pre-release version:

    pip install --upgrade cirq-ionq~=1.0.dev

    If you want to install the full Cirq suite including all optional modules (not just cirq-ionq), use:

    pip install cirq

    or for the pre-release version:

    pip install --upgrade cirq~=1.0.dev