cirq

SKILL.md

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.

Installation

uv pip install cirq

For hardware integration:

# Google Quantum Engine
uv pip install cirq-google

# IonQ
uv pip install cirq-ionq

AQT (Alpine Quantum Technologies)

uv pip install cirq-aqt

Pasqal

uv pip install cirq-pasqal

Azure Quantum

uv pip install azure-quantum cirq

## Quick Start

### Basic Circuit

```python
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()
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 - 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 - 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 - 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 - Complete guide to hardware integration

Supported providers:

Google Quantum AI (cirq-google) - Sycamore, Weber processors

IonQ (cirq-ionq) - Trapped ion quantum computers

Azure Quantum (azure-quantum) - IonQ and Honeywell backends

AQT (cirq-aqt) - Alpine Quantum Technologies

Pasqal (cirq-pasqal) - Neutral atom quantum computers

Topics include device representation, qubit selection, authentication, job management, and circuit optimization for hardware.

Noise Modeling

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

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 - 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
    # Calculate cost based on state
    return np.real(state[0])

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

Hardware Execution Template

def run_on_hardware(circuit, provider='google', device_name='weber', repetitions=1000):
    """Template for running on quantum hardware."""

    if provider == 'google':
        import cirq_google
        engine = cirq_google.get_engine()
        processor = engine.get_processor(device_name)
        job = processor.run(circuit, repetitions=repetitions)
        return job.results()[0]

    elif provider == 'ionq':
        import cirq_ionq
        service = cirq_ionq.Service()
        result = service.run(circuit, repetitions=repetitions, target='qpu')
        return result

    elif provider == 'azure':
        from azure.quantum.cirq import AzureQuantumService
        # Setup workspace...
        service = AzureQuantumService(workspace)
        result = service.run(circuit, repetitions=repetitions, target='ionq.qpu')
        return result

    else:
        raise ValueError(f"Unknown provider: {provider}")

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').items(),
                key=lambda x: x[1]
            )
        }

    return results

# Run study
noise_levels = [0.0, 0.001, 0.01, 0.05, 0.1]
results = noise_comparison_study(circuit, noise_levels)

Best Practices

Circuit Design

Use appropriate qubit types for your topology

Keep circuits modular and reusable

Label measurements with descriptive keys

Validate circuits against device constraints before execution

Simulation

Use state vector simulation for pure states (more efficient)

Use density matrix simulation only when needed (mixed states, noise)

Leverage parameter sweeps instead of individual runs

Monitor memory usage for large systems (2^n grows quickly)

Hardware Execution

Always test on simulators first

Select best qubits using calibration data

Optimize circuits for target hardware gateset

Implement error mitigation for production runs

Store expensive hardware results immediately

Circuit Optimization

Start with high-level built-in transformers

Chain multiple optimizations in sequence

Track depth and gate count reduction

Validate correctness after transformation

Noise Modeling

Use realistic noise models from calibration data

Include all error sources (gate, decoherence, readout)

Characterize before mitigating

Keep circuits shallow to minimize noise accumulation

Experiments

Structure experiments with clear separation (data generation, collection, analysis)

Use ReCirq patterns for reproducibility

Save intermediate results frequently

Parallelize independent tasks

Document thoroughly with metadata

Additional Resources

Official Documentation: https://quantumai.google/cirq

API Reference: https://quantumai.google/reference/python/cirq

Tutorials: https://quantumai.google/cirq/tutorials

Examples: https://github.com/quantumlib/Cirq/tree/master/examples

ReCirq: https://github.com/quantumlib/ReCirq

Common Issues

Circuit too deep for hardware:

Use circuit optimization transformers to reduce depth

See transformation.md for optimization techniques

Memory issues with simulation:

Switch from density matrix to state vector simulator

Reduce number of qubits or use stabilizer simulator for Clifford circuits

Device validation errors:

Check qubit connectivity with device.metadata.nx_graph

Decompose gates to device-native gateset

See hardware.md for device-specific compilation

Noisy simulation too slow:

Density matrix simulation is O(2^2n) - consider reducing qubits

Use noise models selectively on critical operations only

See simulation.md for performance optimization

2