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.

## Installation

```bash
uv pip install cirq
```

For hardware integration:
```bash
# 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

```python
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) - 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](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

```python
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

```python
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

```python
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

{
  "format": "aiskill/v1",
  "skill": {
    "name": "cirq",
    "slug": "cirq",
    "version": "1.0.0",
    "description": "Google quantum computing framework. Use when targeting Google Quantum AI hardware, designing noise-aware circuits, or running quantum characterization experiments. Best for Google hardware, noise modeling, and low-level circuit design. For IBM hardware use qiskit; for quantum ML with autodiff use pennylane; for physics simulations use qutip.",
    "category": "Research",
    "tags": [
      "research-science"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "APACHE-2.0 LICENSE"
  },
  "prompts": {
    "system": "# Cirq - Quantum Computing with Python\r\n\r\nCirq is Google Quantum AI's open-source framework for designing, simulating, and running quantum circuits on quantum computers and simulators.\r\n\r\n## Installation\r\n\r\n```bash\r\nuv pip install cirq\r\n```\r\n\r\nFor hardware integration:\r\n```bash\r\n# Google Quantum Engine\r\nuv pip install cirq-google\r\n\r\n# IonQ\r\nuv pip install cirq-ionq\r\n\r\n# AQT (Alpine Quantum Technologies)\r\nuv pip install cirq-aqt\r\n\r\n# Pasqal\r\nuv pip install cirq-pasqal\r\n\r\n# Azure Quantum\r\nuv pip install azure-quantum cirq\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Circuit\r\n\r\n```python\r\nimport cirq\r\nimport numpy as np\r\n\r\n# Create qubits\r\nq0, q1 = cirq.LineQubit.range(2)\r\n\r\n# Build circuit\r\ncircuit = cirq.Circuit(\r\n    cirq.H(q0),              # Hadamard on q0\r\n    cirq.CNOT(q0, q1),       # CNOT with q0 control, q1 target\r\n    cirq.measure(q0, q1, key='result')\r\n)\r\n\r\nprint(circuit)\r\n\r\n# Simulate\r\nsimulator = cirq.Simulator()\r\nresult = simulator.run(circuit, repetitions=1000)\r\n\r\n# Display results\r\nprint(result.histogram(key='result'))\r\n```\r\n\r\n### Parameterized Circuit\r\n\r\n```python\r\nimport sympy\r\n\r\n# Define symbolic parameter\r\ntheta = sympy.Symbol('theta')\r\n\r\n# Create parameterized circuit\r\ncircuit = cirq.Circuit(\r\n    cirq.ry(theta)(q0),\r\n    cirq.measure(q0, key='m')\r\n)\r\n\r\n# Sweep over parameter values\r\nsweep = cirq.Linspace('theta', start=0, stop=2*np.pi, length=20)\r\nresults = simulator.run_sweep(circuit, params=sweep, repetitions=1000)\r\n\r\n# Process results\r\nfor params, result in zip(sweep, results):\r\n    theta_val = params['theta']\r\n    counts = result.histogram(key='m')\r\n    print(f\"θ={theta_val:.2f}: {counts}\")\r\n```\r\n\r\n## Core Capabilities\r\n\r\n### Circuit Building\r\nFor comprehensive information about building quantum circuits, including qubits, gates, operations, custom gates, and circuit patterns, see:\r\n- **[references/building.md](references/building.md)** - Complete guide to circuit construction\r\n\r\nCommon topics:\r\n- Qubit types (GridQubit, LineQubit, NamedQubit)\r\n- Single and two-qubit gates\r\n- Parameterized gates and operations\r\n- Custom gate decomposition\r\n- Circuit organization with moments\r\n- Standard circuit patterns (Bell states, GHZ, QFT)\r\n- Import/export (OpenQASM, JSON)\r\n- Working with qudits and observables\r\n\r\n### Simulation\r\nFor detailed information about simulating quantum circuits, including exact simulation, noisy simulation, parameter sweeps, and the Quantum Virtual Machine, see:\r\n- **[references/simulation.md](references/simulation.md)** - Complete guide to quantum simulation\r\n\r\nCommon topics:\r\n- Exact simulation (state vector, density matrix)\r\n- Sampling and measurements\r\n- Parameter sweeps (single and multiple parameters)\r\n- Noisy simulation\r\n- State histograms and visualization\r\n- Quantum Virtual Machine (QVM)\r\n- Expectation values and observables\r\n- Performance optimization\r\n\r\n### Circuit Transformation\r\nFor information about optimizing, compiling, and manipulating quantum circuits, see:\r\n- **[references/transformation.md](references/transformation.md)** - Complete guide to circuit transformations\r\n\r\nCommon topics:\r\n- Transformer framework\r\n- Gate decomposition\r\n- Circuit optimization (merge gates, eject Z gates, drop negligible operations)\r\n- Circuit compilation for hardware\r\n- Qubit routing and SWAP insertion\r\n- Custom transformers\r\n- Transformation pipelines\r\n\r\n### Hardware Integration\r\nFor information about running circuits on real quantum hardware from various providers, see:\r\n- **[references/hardware.md](references/hardware.md)** - Complete guide to hardware integration\r\n\r\nSupported providers:\r\n- **Google Quantum AI** (cirq-google) - Sycamore, Weber processors\r\n- **IonQ** (cirq-ionq) - Trapped ion quantum computers\r\n- **Azure Quantum** (azure-quantum) - IonQ and Honeywell backends\r\n- **AQT** (cirq-aqt) - Alpine Quantum Technologies\r\n- **Pasqal** (cirq-pasqal) - Neutral atom quantum computers\r\n\r\nTopics include device representation, qubit selection, authentication, job management, and circuit optimization for hardware.\r\n\r\n### Noise Modeling\r\nFor information about modeling noise, noisy simulation, characterization, and error mitigation, see:\r\n- **[references/noise.md](references/noise.md)** - Complete guide to noise modeling\r\n\r\nCommon topics:\r\n- Noise channels (depolarizing, amplitude damping, phase damping)\r\n- Noise models (constant, gate-specific, qubit-specific, thermal)\r\n- Adding noise to circuits\r\n- Readout noise\r\n- Noise characterization (randomized benchmarking, XEB)\r\n- Noise visualization (heatmaps)\r\n- Error mitigation techniques\r\n\r\n### Quantum Experiments\r\nFor information about designing experiments, parameter sweeps, data collection, and using the ReCirq framework, see:\r\n- **[references/experiments.md](references/experiments.md)** - Complete guide to quantum experiments\r\n\r\nCommon topics:\r\n- Experiment design patterns\r\n- Parameter sweeps and data collection\r\n- ReCirq framework structure\r\n- Common algorithms (VQE, QAOA, QPE)\r\n- Data analysis and visualization\r\n- Statistical analysis and fidelity estimation\r\n- Parallel data collection\r\n\r\n## Common Patterns\r\n\r\n### Variational Algorithm Template\r\n\r\n```python\r\nimport scipy.optimize\r\n\r\ndef variational_algorithm(ansatz, cost_function, initial_params):\r\n    \"\"\"Template for variational quantum algorithms.\"\"\"\r\n\r\n    def objective(params):\r\n        circuit = ansatz(params)\r\n        simulator = cirq.Simulator()\r\n        result = simulator.simulate(circuit)\r\n        return cost_function(result)\r\n\r\n    # Optimize\r\n    result = scipy.optimize.minimize(\r\n        objective,\r\n        initial_params,\r\n        method='COBYLA'\r\n    )\r\n\r\n    return result\r\n\r\n# Define ansatz\r\ndef my_ansatz(params):\r\n    q = cirq.LineQubit(0)\r\n    return cirq.Circuit(\r\n        cirq.ry(params[0])(q),\r\n        cirq.rz(params[1])(q)\r\n    )\r\n\r\n# Define cost function\r\ndef my_cost(result):\r\n    state = result.final_state_vector\r\n    # Calculate cost based on state\r\n    return np.real(state[0])\r\n\r\n# Run optimization\r\nresult = variational_algorithm(my_ansatz, my_cost, [0.0, 0.0])\r\n```\r\n\r\n### Hardware Execution Template\r\n\r\n```python\r\ndef run_on_hardware(circuit, provider='google', device_name='weber', repetitions=1000):\r\n    \"\"\"Template for running on quantum hardware.\"\"\"\r\n\r\n    if provider == 'google':\r\n        import cirq_google\r\n        engine = cirq_google.get_engine()\r\n        processor = engine.get_processor(device_name)\r\n        job = processor.run(circuit, repetitions=repetitions)\r\n        return job.results()[0]\r\n\r\n    elif provider == 'ionq':\r\n        import cirq_ionq\r\n        service = cirq_ionq.Service()\r\n        result = service.run(circuit, repetitions=repetitions, target='qpu')\r\n        return result\r\n\r\n    elif provider == 'azure':\r\n        from azure.quantum.cirq import AzureQuantumService\r\n        # Setup workspace...\r\n        service = AzureQuantumService(workspace)\r\n        result = service.run(circuit, repetitions=repetitions, target='ionq.qpu')\r\n        return result\r\n\r\n    else:\r\n        raise ValueError(f\"Unknown provider: {provider}\")\r\n```\r\n\r\n### Noise Study Template\r\n\r\n```python\r\ndef noise_comparison_study(circuit, noise_levels):\r\n    \"\"\"Compare circuit performance at different noise levels.\"\"\"\r\n\r\n    results = {}\r\n\r\n    for noise_level in noise_levels:\r\n        # Create noisy circuit\r\n        noisy_circuit = circuit.with_noise(cirq.depolarize(p=noise_level))\r\n\r\n        # Simulate\r\n        simulator = cirq.DensityMatrixSimulator()\r\n        result = simulator.run(noisy_circuit, repetitions=1000)\r\n\r\n        # Analyze\r\n        results[noise_level] = {\r\n            'histogram': result.histogram(key='result'),\r\n            'dominant_state': max(\r\n                result.histogram(key='result').items(),\r\n                key=lambda x: x[1]\r\n            )\r\n        }\r\n\r\n    return results\r\n\r\n# Run study\r\nnoise_levels = [0.0, 0.001, 0.01, 0.05, 0.1]\r\nresults = noise_comparison_study(circuit, noise_levels)\r\n```\r\n\r\n## Best Practices\r\n\r\n1. **Circuit Design**\r\n   - Use appropriate qubit types for your topology\r\n   - Keep circuits modular and reusable\r\n   - Label measurements with descriptive keys\r\n   - Validate circuits against device constraints before execution\r\n\r\n2. **Simulation**\r\n   - Use state vector simulation for pure states (more efficient)\r\n   - Use density matrix simulation only when needed (mixed states, noise)\r\n   - Leverage parameter sweeps instead of individual runs\r\n   - Monitor memory usage for large systems (2^n grows quickly)\r\n\r\n3. **Hardware Execution**\r\n   - Always test on simulators first\r\n   - Select best qubits using calibration data\r\n   - Optimize circuits for target hardware gateset\r\n   - Implement error mitigation for production runs\r\n   - Store expensive hardware results immediately\r\n\r\n4. **Circuit Optimization**\r\n   - Start with high-level built-in transformers\r\n   - Chain multiple optimizations in sequence\r\n   - Track depth and gate count reduction\r\n   - Validate correctness after transformation\r\n\r\n5. **Noise Modeling**\r\n   - Use realistic noise models from calibration data\r\n   - Include all error sources (gate, decoherence, readout)\r\n   - Characterize before mitigating\r\n   - Keep circuits shallow to minimize noise accumulation\r\n\r\n6. **Experiments**\r\n   - Structure experiments with clear separation (data generation, collection, analysis)\r\n   - Use ReCirq patterns for reproducibility\r\n   - Save intermediate results frequently\r\n   - Parallelize independent tasks\r\n   - Document thoroughly with metadata\r\n\r\n## Additional Resources\r\n\r\n- **Official Documentation**: https://quantumai.google/cirq\r\n- **API Reference**: https://quantumai.google/reference/python/cirq\r\n- **Tutorials**: https://quantumai.google/cirq/tutorials\r\n- **Examples**: https://github.com/quantumlib/Cirq/tree/master/examples\r\n- **ReCirq**: https://github.com/quantumlib/ReCirq\r\n\r\n## Common Issues\r\n\r\n**Circuit too deep for hardware:**\r\n- Use circuit optimization transformers to reduce depth\r\n- See `transformation.md` for optimization techniques\r\n\r\n**Memory issues with simulation:**\r\n- Switch from density matrix to state vector simulator\r\n- Reduce number of qubits or use stabilizer simulator for Clifford circuits\r\n\r\n**Device validation errors:**\r\n- Check qubit connectivity with device.metadata.nx_graph\r\n- Decompose gates to device-native gateset\r\n- See `hardware.md` for device-specific compilation\r\n\r\n**Noisy simulation too slow:**\r\n- Density matrix simulation is O(2^2n) - consider reducing qubits\r\n- Use noise models selectively on critical operations only\r\n- See `simulation.md` for performance optimization",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The cirq/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/cirq",
    "exported_at": "2026-11-03T07:44:01.058Z"
  }
}

format: aiskill/v1
skill:
  name: cirq
  slug: cirq
  version: 1.0.0
  description: >-
    Google quantum computing framework. Use when targeting Google Quantum AI hardware, designing
    noise-aware circuits, or running quantum characterization experiments. Best for Google hardware,
    noise modeling, and low-level circuit design. For IBM hardware use qiskit; for quantum ML with
    autodiff use pennylane; for physics simulations use qutip.
  category: Research
  tags:
    - research-science
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: APACHE-2.0 LICENSE
prompts:
  system: "# Cirq - Quantum Computing with Python\r\n\r\nCirq is Google Quantum AI's open-source framework for designing, simulating, and running quantum circuits on quantum computers and simulators.\r\n\r\n## Installation\r\n\r\n```bash\r\nuv pip install cirq\r\n```\r\n\r\nFor hardware integration:\r\n```bash\r\n# Google Quantum Engine\r\nuv pip install cirq-google\r\n\r\n# IonQ\r\nuv pip install cirq-ionq\r\n\r\n# AQT (Alpine Quantum Technologies)\r\nuv pip install cirq-aqt\r\n\r\n# Pasqal\r\nuv pip install cirq-pasqal\r\n\r\n# Azure Quantum\r\nuv pip install azure-quantum cirq\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Circuit\r\n\r\n```python\r\nimport cirq\r\nimport numpy as np\r\n\r\n# Create qubits\r\nq0, q1 = cirq.LineQubit.range(2)\r\n\r\n# Build circuit\r\ncircuit = cirq.Circuit(\r\n    cirq.H(q0),              # Hadamard on q0\r\n    cirq.CNOT(q0, q1),       # CNOT with q0 control, q1 target\r\n    cirq.measure(q0, q1, key='result')\r\n)\r\n\r\nprint(circuit)\r\n\r\n# Simulate\r\nsimulator = cirq.Simulator()\r\nresult = simulator.run(circuit, repetitions=1000)\r\n\r\n# Display results\r\nprint(result.histogram(key='result'))\r\n```\r\n\r\n### Parameterized Circuit\r\n\r\n```python\r\nimport sympy\r\n\r\n# Define symbolic parameter\r\ntheta = sympy.Symbol('theta')\r\n\r\n# Create parameterized circuit\r\ncircuit = cirq.Circuit(\r\n    cirq.ry(theta)(q0),\r\n    cirq.measure(q0, key='m')\r\n)\r\n\r\n# Sweep over parameter values\r\nsweep = cirq.Linspace('theta', start=0, stop=2*np.pi, length=20)\r\nresults = simulator.run_sweep(circuit, params=sweep, repetitions=1000)\r\n\r\n# Process results\r\nfor params, result in zip(sweep, results):\r\n    theta_val = params['theta']\r\n    counts = result.histogram(key='m')\r\n    print(f\"θ={theta_val:.2f}: {counts}\")\r\n```\r\n\r\n## Core Capabilities\r\n\r\n### Circuit Building\r\nFor comprehensive information about building quantum circuits, including qubits, gates, operations, custom gates, and circuit patterns, see:\r\n- **[references/building.md](references/building.md)** - Complete guide to circuit construction\r\n\r\nCommon topics:\r\n- Qubit types (GridQubit, LineQubit, NamedQubit)\r\n- Single and two-qubit gates\r\n- Parameterized gates and operations\r\n- Custom gate decomposition\r\n- Circuit organization with moments\r\n- Standard circuit patterns (Bell states, GHZ, QFT)\r\n- Import/export (OpenQASM, JSON)\r\n- Working with qudits and observables\r\n\r\n### Simulation\r\nFor detailed information about simulating quantum circuits, including exact simulation, noisy simulation, parameter sweeps, and the Quantum Virtual Machine, see:\r\n- **[references/simulation.md](references/simulation.md)** - Complete guide to quantum simulation\r\n\r\nCommon topics:\r\n- Exact simulation (state vector, density matrix)\r\n- Sampling and measurements\r\n- Parameter sweeps (single and multiple parameters)\r\n- Noisy simulation\r\n- State histograms and visualization\r\n- Quantum Virtual Machine (QVM)\r\n- Expectation values and observables\r\n- Performance optimization\r\n\r\n### Circuit Transformation\r\nFor information about optimizing, compiling, and manipulating quantum circuits, see:\r\n- **[references/transformation.md](references/transformation.md)** - Complete guide to circuit transformations\r\n\r\nCommon topics:\r\n- Transformer framework\r\n- Gate decomposition\r\n- Circuit optimization (merge gates, eject Z gates, drop negligible operations)\r\n- Circuit compilation for hardware\r\n- Qubit routing and SWAP insertion\r\n- Custom transformers\r\n- Transformation pipelines\r\n\r\n### Hardware Integration\r\nFor information about running circuits on real quantum hardware from various providers, see:\r\n- **[references/hardware.md](references/hardware.md)** - Complete guide to hardware integration\r\n\r\nSupported providers:\r\n- **Google Quantum AI** (cirq-google) - Sycamore, Weber processors\r\n- **IonQ** (cirq-ionq) - Trapped ion quantum computers\r\n- **Azure Quantum** (azure-quantum) - IonQ and Honeywell backends\r\n- **AQT** (cirq-aqt) - Alpine Quantum Technologies\r\n- **Pasqal** (cirq-pasqal) - Neutral atom quantum computers\r\n\r\nTopics include device representation, qubit selection, authentication, job management, and circuit optimization for hardware.\r\n\r\n### Noise Modeling\r\nFor information about modeling noise, noisy simulation, characterization, and error mitigation, see:\r\n- **[references/noise.md](references/noise.md)** - Complete guide to noise modeling\r\n\r\nCommon topics:\r\n- Noise channels (depolarizing, amplitude damping, phase damping)\r\n- Noise models (constant, gate-specific, qubit-specific, thermal)\r\n- Adding noise to circuits\r\n- Readout noise\r\n- Noise characterization (randomized benchmarking, XEB)\r\n- Noise visualization (heatmaps)\r\n- Error mitigation techniques\r\n\r\n### Quantum Experiments\r\nFor information about designing experiments, parameter sweeps, data collection, and using the ReCirq framework, see:\r\n- **[references/experiments.md](references/experiments.md)** - Complete guide to quantum experiments\r\n\r\nCommon topics:\r\n- Experiment design patterns\r\n- Parameter sweeps and data collection\r\n- ReCirq framework structure\r\n- Common algorithms (VQE, QAOA, QPE)\r\n- Data analysis and visualization\r\n- Statistical analysis and fidelity estimation\r\n- Parallel data collection\r\n\r\n## Common Patterns\r\n\r\n### Variational Algorithm Template\r\n\r\n```python\r\nimport scipy.optimize\r\n\r\ndef variational_algorithm(ansatz, cost_function, initial_params):\r\n    \"\"\"Template for variational quantum algorithms.\"\"\"\r\n\r\n    def objective(params):\r\n        circuit = ansatz(params)\r\n        simulator = cirq.Simulator()\r\n        result = simulator.simulate(circuit)\r\n        return cost_function(result)\r\n\r\n    # Optimize\r\n    result = scipy.optimize.minimize(\r\n        objective,\r\n        initial_params,\r\n        method='COBYLA'\r\n    )\r\n\r\n    return result\r\n\r\n# Define ansatz\r\ndef my_ansatz(params):\r\n    q = cirq.LineQubit(0)\r\n    return cirq.Circuit(\r\n        cirq.ry(params[0])(q),\r\n        cirq.rz(params[1])(q)\r\n    )\r\n\r\n# Define cost function\r\ndef my_cost(result):\r\n    state = result.final_state_vector\r\n    # Calculate cost based on state\r\n    return np.real(state[0])\r\n\r\n# Run optimization\r\nresult = variational_algorithm(my_ansatz, my_cost, [0.0, 0.0])\r\n```\r\n\r\n### Hardware Execution Template\r\n\r\n```python\r\ndef run_on_hardware(circuit, provider='google', device_name='weber', repetitions=1000):\r\n    \"\"\"Template for running on quantum hardware.\"\"\"\r\n\r\n    if provider == 'google':\r\n        import cirq_google\r\n        engine = cirq_google.get_engine()\r\n        processor = engine.get_processor(device_name)\r\n        job = processor.run(circuit, repetitions=repetitions)\r\n        return job.results()[0]\r\n\r\n    elif provider == 'ionq':\r\n        import cirq_ionq\r\n        service = cirq_ionq.Service()\r\n        result = service.run(circuit, repetitions=repetitions, target='qpu')\r\n        return result\r\n\r\n    elif provider == 'azure':\r\n        from azure.quantum.cirq import AzureQuantumService\r\n        # Setup workspace...\r\n        service = AzureQuantumService(workspace)\r\n        result = service.run(circuit, repetitions=repetitions, target='ionq.qpu')\r\n        return result\r\n\r\n    else:\r\n        raise ValueError(f\"Unknown provider: {provider}\")\r\n```\r\n\r\n### Noise Study Template\r\n\r\n```python\r\ndef noise_comparison_study(circuit, noise_levels):\r\n    \"\"\"Compare circuit performance at different noise levels.\"\"\"\r\n\r\n    results = {}\r\n\r\n    for noise_level in noise_levels:\r\n        # Create noisy circuit\r\n        noisy_circuit = circuit.with_noise(cirq.depolarize(p=noise_level))\r\n\r\n        # Simulate\r\n        simulator = cirq.DensityMatrixSimulator()\r\n        result = simulator.run(noisy_circuit, repetitions=1000)\r\n\r\n        # Analyze\r\n        results[noise_level] = {\r\n            'histogram': result.histogram(key='result'),\r\n            'dominant_state': max(\r\n                result.histogram(key='result').items(),\r\n                key=lambda x: x[1]\r\n            )\r\n        }\r\n\r\n    return results\r\n\r\n# Run study\r\nnoise_levels = [0.0, 0.001, 0.01, 0.05, 0.1]\r\nresults = noise_comparison_study(circuit, noise_levels)\r\n```\r\n\r\n## Best Practices\r\n\r\n1. **Circuit Design**\r\n   - Use appropriate qubit types for your topology\r\n   - Keep circuits modular and reusable\r\n   - Label measurements with descriptive keys\r\n   - Validate circuits against device constraints before execution\r\n\r\n2. **Simulation**\r\n   - Use state vector simulation for pure states (more efficient)\r\n   - Use density matrix simulation only when needed (mixed states, noise)\r\n   - Leverage parameter sweeps instead of individual runs\r\n   - Monitor memory usage for large systems (2^n grows quickly)\r\n\r\n3. **Hardware Execution**\r\n   - Always test on simulators first\r\n   - Select best qubits using calibration data\r\n   - Optimize circuits for target hardware gateset\r\n   - Implement error mitigation for production runs\r\n   - Store expensive hardware results immediately\r\n\r\n4. **Circuit Optimization**\r\n   - Start with high-level built-in transformers\r\n   - Chain multiple optimizations in sequence\r\n   - Track depth and gate count reduction\r\n   - Validate correctness after transformation\r\n\r\n5. **Noise Modeling**\r\n   - Use realistic noise models from calibration data\r\n   - Include all error sources (gate, decoherence, readout)\r\n   - Characterize before mitigating\r\n   - Keep circuits shallow to minimize noise accumulation\r\n\r\n6. **Experiments**\r\n   - Structure experiments with clear separation (data generation, collection, analysis)\r\n   - Use ReCirq patterns for reproducibility\r\n   - Save intermediate results frequently\r\n   - Parallelize independent tasks\r\n   - Document thoroughly with metadata\r\n\r\n## Additional Resources\r\n\r\n- **Official Documentation**: https://quantumai.google/cirq\r\n- **API Reference**: https://quantumai.google/reference/python/cirq\r\n- **Tutorials**: https://quantumai.google/cirq/tutorials\r\n- **Examples**: https://github.com/quantumlib/Cirq/tree/master/examples\r\n- **ReCirq**: https://github.com/quantumlib/ReCirq\r\n\r\n## Common Issues\r\n\r\n**Circuit too deep for hardware:**\r\n- Use circuit optimization transformers to reduce depth\r\n- See `transformation.md` for optimization techniques\r\n\r\n**Memory issues with simulation:**\r\n- Switch from density matrix to state vector simulator\r\n- Reduce number of qubits or use stabilizer simulator for Clifford circuits\r\n\r\n**Device validation errors:**\r\n- Check qubit connectivity with device.metadata.nx_graph\r\n- Decompose gates to device-native gateset\r\n- See `hardware.md` for device-specific compilation\r\n\r\n**Noisy simulation too slow:**\r\n- Density matrix simulation is O(2^2n) - consider reducing qubits\r\n- Use noise models selectively on critical operations only\r\n- See `simulation.md` for performance optimization"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The cirq/ folder contains SKILL.md
        plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/cirq
  exported_at: "2026-11-03T07:44:01.058Z"