or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

circuits.mddevices.mdindex.mdlinalg.mdops.mdprotocols.mdqis.mdremaining-modules.mdsim.mdstudy.mdtransformers.md
tile.json

tessl/pypi-cirq

A framework for creating, editing, and invoking Noisy Intermediate Scale Quantum (NISQ) circuits.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/cirq@1.6.x

To install, run

npx @tessl/cli install tessl/pypi-cirq@1.6.0

index.mddocs/

Cirq

Cirq is a Python framework for creating, editing, and invoking Noisy Intermediate Scale Quantum (NISQ) circuits. It provides a complete toolkit for quantum circuit design, optimization, simulation, and analysis, with comprehensive support for quantum gates, noise modeling, device characterization, and quantum algorithms.

Package Information

  • Package Name: cirq
  • Package Type: PyPI
  • Language: Python
  • Installation: pip install cirq
  • Minimum Python Version: 3.11

Core Imports

import cirq

# Import specific components
from cirq import Circuit, GridQubit, H, CNOT, measure
from cirq import Simulator, DensityMatrixSimulator
from cirq import LineQubit, X, Y, Z, S, T

# Import for parameter sweeps
from cirq import ParamResolver, Linspace

# Import for noise modeling
from cirq import NoiseModel, DepolarizingChannel

Basic Usage

import cirq
import numpy as np

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

# Build a quantum circuit
circuit = cirq.Circuit()
circuit.append(cirq.H(q0))  # Hadamard gate on qubit 0
circuit.append(cirq.CNOT(q0, q1))  # CNOT gate
circuit.append(cirq.measure(q0, q1, key='result'))  # Measurement

print("Circuit:")
print(circuit)

# Simulate the circuit
simulator = cirq.Simulator()
result = simulator.run(circuit, repetitions=100)
print("Measurement results:")
print(result.histogram(key='result'))

# Get final state vector (without measurement)
circuit_no_measure = circuit[:-1]  # Remove measurement
final_state = simulator.simulate(circuit_no_measure)
print("Final state vector:")
print(final_state.final_state_vector)

Architecture

Cirq follows a layered architecture for quantum computing:

Core Components

  • Circuits & Operations: Quantum circuits composed of moments containing operations
  • Gates & Qubits: Quantum gates acting on qubit identifiers
  • Devices: Hardware constraints and noise models
  • Simulators: Classical simulation of quantum circuits
  • Protocols: Extensible interfaces for quantum operations

Key Abstractions

  • Circuit: Container for quantum operations organized in time-ordered moments
  • Gate: Abstract quantum operation that can be applied to qubits
  • Operation: Instance of a gate applied to specific qubits
  • Moment: Set of operations that occur simultaneously
  • Simulator: Engine for classical quantum circuit simulation

Capabilities

Circuit Construction and Manipulation

Build and manipulate quantum circuits with intuitive Python syntax.

class Circuit:
    def __init__(self, *contents: 'cirq.OP_TREE') -> None: ...
    def append(self, op_tree: 'cirq.OP_TREE', strategy: InsertStrategy = InsertStrategy.NEW_THEN_INLINE) -> None: ...
    def insert(self, index: int, op_tree: 'cirq.OP_TREE', strategy: InsertStrategy = InsertStrategy.NEW_THEN_INLINE) -> None: ...
    def moments(self) -> List[Moment]: ...
    def all_qubits(self) -> FrozenSet['cirq.Qid']: ...
    def num_qubits(self) -> int: ...
    
class Moment:
    def __init__(self, *operations: 'cirq.Operation') -> None: ...
    def operates_on(self, qubits: Iterable['cirq.Qid']) -> bool: ...
    def operations(self) -> FrozenSet['cirq.Operation']: ...

Circuits and Moments

Quantum Gates and Operations

Comprehensive library of quantum gates including Pauli gates, rotation gates, multi-qubit gates, and noise channels.

# Single-qubit gates
X: XPowGate
Y: YPowGate  
Z: ZPowGate
H: HPowGate
S: ZPowGate  # S gate (phase gate)
T: ZPowGate  # T gate

# Rotation gates
def rx(rads: float) -> XPowGate: ...
def ry(rads: float) -> YPowGate: ...
def rz(rads: float) -> ZPowGate: ...

# Multi-qubit gates
CNOT: CNotPowGate
CZ: CZPowGate
SWAP: SwapPowGate
TOFFOLI: CCXPowGate

Gates and Operations

Quantum Circuit Simulation

Multiple simulation backends for different use cases and performance requirements.

class Simulator(SimulatorBase):
    def run(self, program: 'cirq.CIRCUIT_LIKE', param_resolver: 'cirq.ParamResolverOrSimilarType' = None, 
            repetitions: int = 1) -> 'cirq.Result': ...
    def simulate(self, program: 'cirq.CIRCUIT_LIKE', param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
                initial_state: 'cirq.STATE_VECTOR_LIKE' = None) -> SimulationTrialResult: ...

class DensityMatrixSimulator(SimulatorBase):
    def simulate(self, program: 'cirq.CIRCUIT_LIKE', param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
                initial_state: 'cirq.QUANTUM_STATE_LIKE' = None) -> DensityMatrixTrialResult: ...

Simulators and Simulation

Device Modeling and Noise

Model quantum hardware constraints and realistic noise for NISQ applications.

class GridQubit(Qid):
    def __init__(self, row: int, col: int) -> None: ...
    @property
    def row(self) -> int: ...
    @property
    def col(self) -> int: ...

class NoiseModel:
    def noisy_operation(self, operation: 'cirq.Operation') -> 'cirq.OP_TREE': ...

def depolarize(p: float, n_qubits: int = None) -> DepolarizingChannel: ...

Devices and Noise Modeling

Parameter Sweeps and Studies

Run parameterized experiments and parameter sweeps for algorithm optimization.

class ParamResolver:
    def __init__(self, param_dict: Dict[Union[str, sympy.Symbol], Any] = None) -> None: ...
    def resolve(self, value: Any) -> Any: ...

class Linspace(Sweep):
    def __init__(self, key: Union[str, sympy.Symbol], start: float, stop: float, length: int) -> None: ...

def sample_sweep(program: 'cirq.CIRCUIT_LIKE', params: 'cirq.Sweepable', 
                repetitions: int = 1) -> List['cirq.Result']: ...

Parameter Studies

Quantum Information Science Tools

Utilities for quantum state manipulation, channel representations, and quantum information measures.

def fidelity(state1: 'cirq.QUANTUM_STATE_LIKE', state2: 'cirq.QUANTUM_STATE_LIKE') -> float: ...
def von_neumann_entropy(state: 'cirq.QUANTUM_STATE_LIKE') -> float: ...
def kraus_to_choi(kraus_operators: Sequence[np.ndarray]) -> np.ndarray: ...
def density_matrix_from_state_vector(state_vector: np.ndarray) -> np.ndarray: ...

Quantum Information Science

Linear Algebra and Mathematical Utilities

Mathematical functions for quantum computing including matrix decompositions and special operations.

def kak_decomposition(unitary: np.ndarray) -> KakDecomposition: ...
def is_unitary(matrix: np.ndarray) -> bool: ...
def partial_trace(tensor: np.ndarray, keep_indices: List[int], qid_shape: Tuple[int, ...]) -> np.ndarray: ...

Linear Algebra

Circuit Transformers and Optimization

Transform and optimize quantum circuits for different target hardware and improved performance.

def merge_single_qubit_gates_to_phxz(circuit: Circuit, context: TransformerContext = None) -> Circuit: ...
def optimize_for_target_gateset(circuit: Circuit, gateset: CompilationTargetGateset) -> Circuit: ...
def single_qubit_matrix_to_gates(matrix: np.ndarray, tolerance: float = 1e-10) -> List['cirq.Operation']: ...

Transformers and Optimization

Protocols and Extensibility

Extensible protocol system for adding custom behavior to quantum operations.

def unitary(val: Any) -> np.ndarray: ...
def decompose(val: Any, intercepting_decomposer: Callable = None) -> List['cirq.Operation']: ...
def apply_unitary(val: Any, args: ApplyUnitaryArgs) -> Union[np.ndarray, None]: ...

Protocols

Visualization and Analysis

Tools for visualizing quantum circuits, states, and measurement results.

def plot_state_histogram(result: 'cirq.Result', ax: matplotlib.axes.Axes = None) -> matplotlib.axes.Axes: ...
def plot_density_matrix(matrix: np.ndarray) -> None: ...
class Heatmap:
    def __init__(self, value_map: Mapping[Tuple[int, ...], float]) -> None: ...

Visualization

Quantum Experiments and Characterization

Built-in experiments for quantum device characterization and benchmarking.

def single_qubit_randomized_benchmarking(sampler: 'cirq.Sampler', qubit: 'cirq.Qid', 
                                       use_cliffords: bool = True) -> RandomizedBenchMarkResult: ...
def xeb_fidelity(circuit_results: Dict['cirq.Circuit', List[int]], 
                simulated_probs: Dict['cirq.Circuit', np.ndarray]) -> float: ...

Experiments and Characterization

Value Types and Utilities

Utility classes for time, measurement keys, classical data, and other quantum computing values.

class Duration:
    def __init__(self, *, picos: int = 0, nanos: int = 0, micros: int = 0, millis: int = 0) -> None: ...

class MeasurementKey:
    def __init__(self, name: str, path: Tuple[str, ...] = ()) -> None: ...

Value Types and Utilities

Workflow and Sampling

High-level workflow utilities for quantum computation and measurement collection.

class Sampler:
    def run(self, program: 'cirq.CIRCUIT_LIKE', param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
            repetitions: int = 1) -> 'cirq.Result': ...

class PauliSumCollector:
    def __init__(self, circuit: 'cirq.Circuit', observables: List['cirq.PauliSum'],
                 sampler: 'cirq.Sampler') -> None: ...

Workflow and Sampling

Interoperability

Integration with other quantum computing frameworks and tools.

def quirk_json_to_circuit(json_text: str) -> Circuit: ...
def quirk_url_to_circuit(url: str) -> Circuit: ...

Interoperability

Type System

# Core type aliases
OP_TREE = Union[Operation, Iterable['OP_TREE']]
CIRCUIT_LIKE = Union[Circuit, FrozenCircuit, Iterable[Any]]
QUANTUM_STATE_LIKE = Union[int, np.ndarray, 'cirq.QuantumState']
STATE_VECTOR_LIKE = Union[int, np.ndarray, Sequence[Union[int, float, complex]]]
PAULI_STRING_LIKE = Union[PauliString, str]
PAULI_GATE_LIKE = Union[Pauli, PauliString, str]
DURATION_LIKE = Union[Duration, float, int]
RANDOM_STATE_OR_SEED_LIKE = Union[int, np.random.RandomState, np.random.Generator]

# Parameter types  
ParamDictType = Mapping[Union[str, sympy.Symbol], Any]
ParamResolverOrSimilarType = Union[ParamResolver, ParamDictType, Iterable[Any]]
Sweepable = Union[Sweep, ParamResolver, ParamDictType, Iterable[Any]]

This comprehensive documentation covers all major capabilities of the cirq quantum computing framework, enabling developers to build, simulate, and analyze quantum circuits without needing to access the source code directly.