Back to Details

cirq

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cirq - Quantum Computing with Python

Cirq - 基于Python的量子计算

Cirq is Google Quantum AI's open-source framework for designing, simulating, and running quantum circuits on quantum computers and simulators.
Cirq是Google Quantum AI推出的开源框架，用于在量子计算机和模拟器上设计、模拟和运行量子电路。

Installation

安装

bash
uv pip install cirq
For hardware integration:
bash
undefined
bash
uv pip install cirq
如需硬件集成：
bash
undefined

Google Quantum Engine

Google Quantum Engine

uv pip install cirq-google
uv pip install cirq-google

IonQ

IonQ

uv pip install cirq-ionq
uv pip install cirq-ionq

AQT (Alpine Quantum Technologies)

AQT (Alpine Quantum Technologies)

uv pip install cirq-aqt
uv pip install cirq-aqt

Pasqal

Pasqal

uv pip install cirq-pasqal
uv pip install cirq-pasqal

Azure Quantum

Azure Quantum

uv pip install azure-quantum cirq
undefined
uv pip install azure-quantum cirq
undefined

Quick Start

快速开始

Basic Circuit

基础电路

python
import cirq
import numpy as np
python
import cirq
import numpy as np

Create qubits

创建量子比特

q0, q1 = cirq.LineQubit.range(2)
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)
circuit = cirq.Circuit( cirq.H(q0), # 在q0上应用Hadamard门 cirq.CNOT(q0, q1), # 以q0为控制位、q1为目标位的CNOT门 cirq.measure(q0, q1, key='result') )
print(circuit)

Simulate

模拟

simulator = cirq.Simulator() result = simulator.run(circuit, repetitions=1000)
simulator = cirq.Simulator() result = simulator.run(circuit, repetitions=1000)

Display results

展示结果

print(result.histogram(key='result'))
undefined
print(result.histogram(key='result'))
undefined

Parameterized Circuit

参数化电路

python
import sympy
python
import sympy

Define symbolic parameter

定义符号参数

theta = sympy.Symbol('theta')
theta = sympy.Symbol('theta')

Create parameterized circuit

创建参数化电路

circuit = cirq.Circuit( cirq.ry(theta)(q0), cirq.measure(q0, key='m') )
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)
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}")
undefined
for params, result in zip(sweep, results): theta_val = params['theta'] counts = result.histogram(key='m') print(f"θ={theta_val:.2f}: {counts}")
undefined

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
关于构建量子电路的全面信息，包括量子比特、门、操作、自定义门和电路模式，请参阅：
  • references/building.md - 电路构建完整指南
常见主题：
  • 量子比特类型（GridQubit、LineQubit、NamedQubit）
  • 单量子比特和双量子比特门
  • 参数化门与操作
  • 自定义门分解
  • 用时刻组织电路
  • 标准电路模式（贝尔态、GHZ态、QFT）
  • 导入/导出（OpenQASM、JSON）
  • 量子位与可观测量的使用

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
关于量子电路模拟的详细信息，包括精确模拟、含噪声模拟、参数遍历和量子虚拟机，请参阅：
  • references/simulation.md - 量子模拟完整指南
常见主题：
  • 精确模拟（态矢量、密度矩阵）
  • 采样与测量
  • 参数遍历（单参数和多参数）
  • 含噪声模拟
  • 态直方图与可视化
  • 量子虚拟机（QVM）
  • 期望值与可观测量
  • 性能优化

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
关于优化、编译和操作量子电路的信息，请参阅：
  • references/transformation.md - 电路转换完整指南
常见主题：
  • 转换器框架
  • 门分解
  • 电路优化（合并门、移除Z门、丢弃可忽略操作）
  • 面向硬件的电路编译
  • 量子比特路由与SWAP插入
  • 自定义转换器
  • 转换流水线

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.
关于在不同供应商的真实量子硬件上运行电路的信息，请参阅：
  • references/hardware.md - 硬件集成完整指南
支持的供应商：
  • Google Quantum AI（cirq-google）- Sycamore、Weber处理器
  • IonQ（cirq-ionq）- 离子阱量子计算机
  • Azure Quantum（azure-quantum）- IonQ和Honeywell后端
  • AQT（cirq-aqt）- Alpine Quantum Technologies
  • Pasqal（cirq-pasqal）- 中性原子量子计算机
主题包括设备表示、量子比特选择、身份验证、作业管理和面向硬件的电路优化。

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
关于噪声建模、含噪声模拟、表征和错误缓解的信息，请参阅：
  • references/noise.md - 噪声建模完整指南
常见主题：
  • 噪声信道（退极化、振幅阻尼、相位阻尼）
  • 噪声模型（恒定、门专属、量子比特专属、热噪声）
  • 为电路添加噪声
  • 读出噪声
  • 噪声表征（随机基准测试、XEB）
  • 噪声可视化（热图）
  • 错误缓解技术

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
关于实验设计、参数遍历、数据收集和ReCirq框架使用的信息，请参阅：
  • references/experiments.md - 量子实验完整指南
常见主题：
  • 实验设计模式
  • 参数遍历与数据收集
  • ReCirq框架结构
  • 常见算法（VQE、QAOA、QPE）
  • 数据分析与可视化
  • 统计分析与保真度估计
  • 并行数据收集

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
python
import scipy.optimize

def variational_algorithm(ansatz, cost_function, initial_params):
    """变分量子算法模板。"""

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

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

    return result

Define ansatz

定义ansatz

def my_ansatz(params): q = cirq.LineQubit(0) return cirq.Circuit( cirq.ry(params[0])(q), cirq.rz(params[1])(q) )
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])
def my_cost(result): state = result.final_state_vector # 基于态计算代价 return np.real(state[0])

Run optimization

运行优化

result = variational_algorithm(my_ansatz, my_cost, [0.0, 0.0])
undefined
result = variational_algorithm(my_ansatz, my_cost, [0.0, 0.0])
undefined

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}")
python
def run_on_hardware(circuit, provider='google', device_name='weber', repetitions=1000):
    """在量子硬件上运行的模板。"""

    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
        # 设置工作区...
        service = AzureQuantumService(workspace)
        result = service.run(circuit, repetitions=repetitions, target='ionq.qpu')
        return result

    else:
        raise ValueError(f"未知供应商: {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
python
def noise_comparison_study(circuit, noise_levels):
    """比较不同噪声水平下的电路性能。"""

    results = {}

    for noise_level in noise_levels:
        # 创建含噪声电路
        noisy_circuit = circuit.with_noise(cirq.depolarize(p=noise_level))

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

        # 分析
        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)
undefined
noise_levels = [0.0, 0.001, 0.01, 0.05, 0.1] results = noise_comparison_study(circuit, noise_levels)
undefined

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
  1. 电路设计
    • 为你的拓扑选择合适的量子比特类型
    • 保持电路模块化和可复用
    • 为测量添加描述性键名
    • 在执行前根据设备约束验证电路
  2. 模拟
    • 对纯态使用态矢量模拟（效率更高）
    • 仅在需要时使用密度矩阵模拟（混合态、噪声场景）
    • 利用参数遍历替代单独运行
    • 监控大型系统的内存使用（2^n增长迅速）
  3. 硬件执行
    • 始终先在模拟器上测试
    • 使用校准数据选择最优量子比特
    • 针对目标硬件的门集优化电路
    • 为生产运行实现错误缓解
    • 立即存储昂贵的硬件运行结果
  4. 电路优化
    • 从高级内置转换器开始
    • 按顺序组合多种优化
    • 跟踪深度和门数量的减少
    • 转换后验证正确性
  5. 噪声建模
    • 使用来自校准数据的真实噪声模型
    • 包含所有误差源（门、退相干、读出）
    • 先表征再缓解
    • 保持电路浅度以最小化噪声累积
  6. 实验
    • 清晰划分实验结构（数据生成、收集、分析）
    • 使用ReCirq模式确保可复现性
    • 频繁保存中间结果
    • 并行化独立任务
    • 用元数据全面记录

Additional Resources

其他资源

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
电路对硬件来说过深：
  • 使用电路优化转换器减少深度
  • 参阅
    transformation.md
    了解优化技术
模拟时内存不足：
  • 从密度矩阵模拟器切换为态矢量模拟器
  • 减少量子比特数量，或对克利福德电路使用稳定器模拟器
设备验证错误：
  • 通过device.metadata.nx_graph检查量子比特连通性
  • 将门分解为设备原生门集
  • 参阅
    hardware.md
    了解设备专属编译方法
含噪声模拟过慢：
  • 密度矩阵模拟的复杂度为O(2^2n) - 考虑减少量子比特数量
  • 仅在关键操作上选择性使用噪声模型
  • 参阅
    simulation.md
    了解性能优化方法