cirq – Design & UI skill for AI agents

Cirq - Quantum Computing with Python

Cirq is Google Quantum AI's open-source framework for designing, simulating, and running quantum circuits on quantum computers and simulators.

When to Use This Skill

Use this skill when:

• Building, simulating, or optimizing NISQ circuits in Python
• Running jobs on Google Quantum AI processors (via cirq-google) or partner backends (IonQ, Azure Quantum, AQT, Pasqal)
• Modeling noise, compiling to hardware gatesets, or designing characterization experiments
• Using parameter sweeps, transformers, or the ReCirq experiment patterns

For IBM hardware use qiskit; for quantum ML with autodiff use pennylane; for physics simulations use qutip.

Installation

Examples target Cirq 1.7.0 on Python 3.11+. Keep Cirq vendor packages on the matching release; independently versioned integrations such as Azure Quantum need their own compatibility check.

uv pip install "cirq-core==1.7.0"
# Optional OpenQASM import dependency
uv pip install ply

For hardware integration (pin matching versions for reproducibility):

# Google Quantum Engine (requires approved GCP project access)
uv pip install "cirq-google==1.7.0"

# IonQ
uv pip install "cirq-ionq==1.7.0"

# AQT (Alpine Quantum Technologies)
uv pip install "cirq-aqt==1.7.0"

# Pasqal
uv pip install "cirq-pasqal==1.7.0"

# Azure: use a SEPARATE environment; its current extras require Cirq <1.7.
uv pip install "qdk[azure,cirq]==1.32.3" "azure-quantum==3.13.0"

Pin all cirq-* packages in an environment to the same release. The Azure

example targets its supported Cirq 1.6.1 stack separately; do not force Cirq 1.7.0

into it. Cirq 1.7.0 updates the IonQ adapter to API v0.4.

Local examples were checked with synthetic circuits. Hardware examples are

illustrative and were checked against released source and provider documentation,

without submitting cloud jobs. See [review evidence](references/review.md).

Quick Start

Basic Circuit

import cirq
import numpy as np

# Create qubits
q0, q1 = cirq.LineQubit.range(2)

# Build circuit
circuit = cirq.Circuit(
    cirq.H(q0),              # Hadamard on q0
    cirq.CNOT(q0, q1),       # CNOT with q0 control, q1 target
    cirq.measure(q0, q1, key='result')
)

print(circuit)

# Simulate
simulator = cirq.Simulator(seed=42)
result = simulator.run(circuit, repetitions=1000)

# Display results
print(result.histogram(key='result'))

Parameterized Circuit

import sympy

# Define symbolic parameter
theta = sympy.Symbol('theta')

# Create parameterized circuit
circuit = cirq.Circuit(
    cirq.ry(theta)(q0),
    cirq.measure(q0, key='m')
)

# Sweep over parameter values
sweep = cirq.Linspace('theta', start=0, stop=2*np.pi, length=20)
results = simulator.run_sweep(circuit, params=sweep, repetitions=1000)

# Process results
for params, result in zip(sweep, results):
    theta_val = params['theta']
    counts = result.histogram(key='m')
    print(f"θ={theta_val:.2f}: {counts}")

Core Capabilities

Circuit Building

For comprehensive information about building quantum circuits, including qubits, gates, operations, custom gates, and circuit patterns, see:

• [references/building.md](references/building.md) - Complete guide to circuit construction

Common topics:

• Qubit types (GridQubit, LineQubit, NamedQubit)
• Single and two-qubit gates
• Parameterized gates and operations
• Custom gate decomposition
• Circuit organization with moments
• Standard circuit patterns (Bell states, GHZ, QFT)
• Import/export (OpenQASM, JSON)
• Working with qudits and observables

Simulation

For detailed information about simulating quantum circuits, including exact simulation, noisy simulation, parameter sweeps, and the Quantum Virtual Machine, see:

• [references/simulation.md](references/simulation.md) - Complete guide to quantum simulation

Common topics:

• Exact simulation (state vector, density matrix)
• Sampling and measurements
• Parameter sweeps (single and multiple parameters)
• Noisy simulation
• State histograms and visualization
• Quantum Virtual Machine (QVM)
• Expectation values and observables
• Performance optimization

Circuit Transformation

For information about optimizing, compiling, and manipulating quantum circuits, see:

• [references/transformation.md](references/transformation.md) - Complete guide to circuit transformations

Common topics:

• Transformer framework
• Gate decomposition
• Circuit optimization (merge gates, eject Z gates, drop negligible operations)
• Circuit compilation for hardware
• Qubit routing and SWAP insertion
• Custom transformers
• Transformation pipelines

Hardware Integration

For information about running circuits on real quantum hardware from various providers, see:

• [references/hardware.md](references/hardware.md) - Complete guide to hardware integration

Supported providers:

• Google Quantum AI (cirq-google) — assigned processors via Quantum Engine; discover IDs from your approved project. Bundled virtual processor names are not proof of live access.
• IonQ (cirq-ionq) — trapped-ion QPUs and simulators
• Azure Quantum (qdk[azure,cirq]) — discover Cirq-compatible targets in your workspace, in its separate supported environment
• AQT (cirq-aqt) — Alpine Quantum Technologies
• Pasqal (cirq-pasqal) — local device modeling; the legacy remote sampler is not a verified current Pasqal Cloud integration

Topics include device representation, qubit selection, authentication, job management, and circuit optimization for hardware. See [Access and authentication](https://quantumai.google/cirq/google/access) for Google Cloud setup.

Noise Modeling

For information about modeling noise, noisy simulation, characterization, and error mitigation, see:

• [references/noise.md](references/noise.md) - Complete guide to noise modeling

Common topics:

• Noise channels (depolarizing, amplitude damping, phase damping)
• Noise models (constant, gate-specific, qubit-specific, thermal)
• Adding noise to circuits
• Readout noise
• Noise characterization (randomized benchmarking, XEB)
• Noise visualization (heatmaps)
• Error mitigation techniques

Quantum Experiments

For information about designing experiments, parameter sweeps, data collection, and using the ReCirq framework, see:

• [references/experiments.md](references/experiments.md) - Complete guide to quantum experiments

Common topics:

• Experiment design patterns
• Parameter sweeps and data collection
• ReCirq framework structure
• Common algorithms (VQE, QAOA, QPE)
• Data analysis and visualization
• Statistical analysis and fidelity estimation
• Parallel data collection

Common Patterns

Variational Algorithm Template

import scipy.optimize

def variational_algorithm(ansatz, cost_function, initial_params):
    """Template for variational quantum algorithms."""

    def objective(params):
        circuit = ansatz(params)
        simulator = cirq.Simulator()
        result = simulator.simulate(circuit)
        return cost_function(result)

    # Optimize
    result = scipy.optimize.minimize(
        objective,
        initial_params,
        method='COBYLA'
    )

    return result

# Define ansatz
def my_ansatz(params):
    q = cirq.LineQubit(0)
    return cirq.Circuit(
        cirq.ry(params[0])(q),
        cirq.rz(params[1])(q)
    )

# Define cost function
def my_cost(result):
    state = result.final_state_vector
    # Single-qubit Pauli-Z expectation; invariant to global phase.
    return float(abs(state[0])**2 - abs(state[1])**2)

# Run optimization
result = variational_algorithm(my_ansatz, my_cost, [0.0, 0.0])

Hardware Execution Template

Illustrative: requires provider credentials, assigned processor IDs, and current

provider target names. The local simulation examples do not validate QPU access.

import cirq

def run_on_hardware(circuit, sampler, device, repetitions=1000):
    """Submit an already routed/compiled circuit to an explicitly chosen sampler."""
    device.validate_circuit(circuit)
    return sampler.run(circuit, repetitions=repetitions)

Configure a provider-specific sampler using [hardware.md](references/hardware.md).

Select the target explicitly; compilation does not itself route disconnected

qubits or guarantee hardware access.

Noise Study Template

def noise_comparison_study(circuit, noise_levels):
    """Compare circuit performance at different noise levels."""

    results = {}

    for noise_level in noise_levels:
        # Create noisy circuit
        noisy_circuit = circuit.with_noise(cirq.depolarize(p=noise_level))

        # Simulate
        simulator = cirq.DensityMatrixSimulator()
        result = simulator.run(noisy_circuit, repetitions=1000)

        # Analyze
        results[noise_level] = {
            'histogram': result.histogram(key='result'),
            'dominant_state': max(
                result.histogram(key='result'

… (full content is in the download package)