Regtransfers/cirq

@ 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

• You are designing, simulating, or executing quantum circuits with the Cirq ecosystem.
• You need Google Quantum AI-style primitives, parameterized circuits, or integrations like cirq-google and cirq-ionq.
• You are prototyping or teaching quantum workflows in Python and want concrete circuit examples.

@ 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

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

1. 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

2. 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)

3. 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

4. Circuit Optimization

• Start with high-level built-in transformers
• Chain multiple optimizations in sequence
• Track depth and gate count reduction
• Validate correctness after transformation

5. 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

6. 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

@ Limitations

• Use this skill only when the task clearly matches the scope described above.
• never treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.