CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-cirq

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

ops.mddocs/

Gates and Operations

The ops module provides the fundamental building blocks for quantum circuits: gates, operations, qubits, and gate sets. It includes a comprehensive library of quantum gates ranging from basic Pauli gates to complex multi-qubit operations and noise channels.

Core Abstractions

Gate - Base Class for Quantum Gates

Abstract base class for quantum gates that can be applied to qubits.

class Gate:
    """Abstract base class for quantum gates."""
    
    @abc.abstractmethod
    def _num_qubits_(self) -> int:
        """Number of qubits this gate acts on."""
        
    def num_qubits(self) -> int:
        """Number of qubits this gate acts on."""
        
    def on(self, *qubits: 'cirq.Qid') -> 'cirq.Operation':
        """Apply this gate to the given qubits, creating an Operation."""
        
    def on_each(self, *targets: Iterable['cirq.Qid']) -> List['cirq.Operation']:
        """Apply this gate to each qubit/set of qubits."""
        
    def wrap_in_linear_combination(self, coefficient: Union[complex, float] = 1) -> 'cirq.LinearCombinationOfGates':
        """Wrap gate in a linear combination with given coefficient."""
        
    def controlled(self, num_controls: int = None, 
                  control_values: Sequence[Union[int, Collection[int]]] = None,
                  control_qid_shape: Sequence[int] = None) -> 'cirq.ControlledGate':
        """Create a controlled version of this gate."""
        
    def with_probability(self, probability: float) -> 'cirq.RandomGateChannel':
        """Create a probabilistic channel that applies this gate."""
        
    def __pow__(self, exponent: Union[float, sympy.Symbol]) -> 'cirq.Gate':
        """Raise gate to a power."""
        
    def __mul__(self, other) -> Union['cirq.LinearCombinationOfGates', NotImplemented]:
        """Multiply gates (tensor product or linear combination)."""

Operation - Gate Applied to Specific Qubits

Represents a gate applied to specific qubits.

class Operation:
    """Abstract base class for quantum operations."""
    
    @property
    @abc.abstractmethod
    def gate(self) -> Optional['cirq.Gate']:
        """The gate applied by this operation."""
        
    @property
    @abc.abstractmethod  
    def qubits(self) -> Tuple['cirq.Qid', ...]:
        """Qubits targeted by this operation."""
        
    def with_qubits(self, *new_qubits: 'cirq.Qid') -> 'cirq.Operation':
        """Return a copy with different target qubits."""
        
    def controlled_by(self, *control_qubits: 'cirq.Qid', 
                     control_values: Union[None, int, Iterable[Union[None, int]]] = None) -> 'cirq.Operation':
        """Add control qubits to this operation."""
        
    def with_tags(self, *new_tags) -> 'cirq.Operation':
        """Return a copy with additional tags."""
        
    def without_tags(self, *tags_to_remove) -> 'cirq.Operation':
        """Return a copy with specified tags removed."""
        
    def with_probability(self, probability: float) -> 'cirq.Operation':
        """Wrap in probabilistic channel."""
        
    def __pow__(self, exponent) -> 'cirq.Operation':
        """Raise operation to a power."""
        
    def transform_qubits(self, qubit_map: Dict['cirq.Qid', 'cirq.Qid']) -> 'cirq.Operation':
        """Transform qubits according to mapping."""

TaggedOperation

Operation with associated metadata tags.

class TaggedOperation(Operation):
    """Operation with associated metadata tags."""
    
    def __init__(self, sub_operation: Operation, *tags) -> None:
        """Initialize tagged operation."""
        
    @property
    def sub_operation(self) -> Operation:
        """The wrapped operation."""
        
    @property
    def tags(self) -> FrozenSet:
        """Tags associated with this operation."""

Single-Qubit Gates

Pauli Gates

The fundamental single-qubit Pauli operators.

class XPowGate(EigenGate):
    """X rotation gate: X^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize X power gate."""
        
    def _eigen_components(self) -> List[Tuple[float, np.ndarray]]:
        """Eigenvalues and eigenvectors of X gate."""

class YPowGate(EigenGate):
    """Y rotation gate: Y^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize Y power gate."""

class ZPowGate(EigenGate):
    """Z rotation gate: Z^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize Z power gate."""

# Common gate instances
X: XPowGate  # Pauli-X gate
Y: YPowGate  # Pauli-Y gate  
Z: ZPowGate  # Pauli-Z gate

Rotation Gates

Parameterized rotation gates around different axes.

def rx(rads: float) -> XPowGate:
    """X-axis rotation by given radians."""
    
def ry(rads: float) -> YPowGate:
    """Y-axis rotation by given radians."""
    
def rz(rads: float) -> ZPowGate:
    """Z-axis rotation by given radians."""

class Rx(XPowGate):
    """X rotation gate specified in radians."""
    
    def __init__(self, rads: Union[float, sympy.Symbol]) -> None:
        """Initialize X rotation."""

class Ry(YPowGate):
    """Y rotation gate specified in radians."""
    
    def __init__(self, rads: Union[float, sympy.Symbol]) -> None:
        """Initialize Y rotation."""

class Rz(ZPowGate):
    """Z rotation gate specified in radians."""
    
    def __init__(self, rads: Union[float, sympy.Symbol]) -> None:
        """Initialize Z rotation."""

Hadamard and Phase Gates

class HPowGate(EigenGate):
    """Hadamard power gate: H^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize Hadamard power gate."""

H: HPowGate  # Hadamard gate
S: ZPowGate  # S gate (√Z, phase gate)
T: ZPowGate  # T gate (∜Z)

Phased Rotation Gates

Advanced single-qubit gates with phase parameters.

class PhasedXPowGate(Gate):
    """Phased X rotation gate."""
    
    def __init__(self, *, phase_exponent: Union[float, sympy.Symbol],
                 exponent: Union[float, sympy.Symbol] = 1.0,
                 global_shift: float = 0.0) -> None:
        """Initialize phased X power gate."""
        
    @property
    def phase_exponent(self) -> Union[float, sympy.Symbol]:
        """Phase parameter."""
        
    @property
    def exponent(self) -> Union[float, sympy.Symbol]:
        """Rotation exponent."""

class PhasedXZGate(Gate):
    """Combined phased X and Z gate."""
    
    def __init__(self, *, x_exponent: Union[float, sympy.Symbol],
                 z_exponent: Union[float, sympy.Symbol],
                 axis_phase_exponent: Union[float, sympy.Symbol]) -> None:
        """Initialize phased XZ gate."""

Identity and Global Phase

class IdentityGate(Gate):
    """Identity gate."""
    
    def __init__(self, qid_shape: Tuple[int, ...] = (2,),
                 *, num_qubits: Optional[int] = None) -> None:
        """Initialize identity gate."""

class GlobalPhaseGate(Gate):
    """Global phase gate."""
    
    def __init__(self, coefficient: Union[float, complex, sympy.Symbol]) -> None:
        """Initialize global phase gate."""

I: IdentityGate  # Identity gate

def identity_each(*qubits: 'cirq.Qid') -> List[Operation]:
    """Apply identity to each qubit."""
    
def global_phase_operation(coefficient: Union[complex, float, sympy.Symbol]) -> Operation:
    """Create global phase operation."""

Two-Qubit Gates

CNOT and Controlled Gates

class CNotPowGate(EigenGate):
    """Controlled-NOT power gate: CNOT^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize CNOT power gate."""

class CXPowGate(CNotPowGate):
    """Alias for CNotPowGate."""

class CZPowGate(EigenGate):
    """Controlled-Z power gate: CZ^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize CZ power gate."""

# Common instances
CNOT: CNotPowGate  # Controlled-NOT gate
CX: CXPowGate      # Alias for CNOT
CZ: CZPowGate      # Controlled-Z gate

def cphase(turns: Union[float, sympy.Symbol]) -> CZPowGate:
    """Controlled phase gate."""

SWAP Gates

class SwapPowGate(EigenGate):
    """SWAP power gate: SWAP^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize SWAP power gate."""

class ISwapPowGate(EigenGate):
    """iSWAP power gate: iSWAP^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize iSWAP power gate."""

SWAP: SwapPowGate       # SWAP gate
ISWAP: ISwapPowGate     # iSWAP gate
SQRT_ISWAP: ISwapPowGate    # √iSWAP gate  
SQRT_ISWAP_INV: ISwapPowGate  # √iSWAP† gate

def riswap(rads: Union[float, sympy.Symbol]) -> ISwapPowGate:
    """Parameterized iSWAP gate."""

Fermionic Simulation Gates

Gates designed for fermionic quantum simulation.

class FSimGate(Gate):
    """Fermionic simulation gate."""
    
    def __init__(self, theta: Union[float, sympy.Symbol], phi: Union[float, sympy.Symbol]) -> None:
        """Initialize FSim gate with theta and phi parameters."""
        
    @property
    def theta(self) -> Union[float, sympy.Symbol]:
        """Theta parameter (iSWAP-like rotation)."""
        
    @property  
    def phi(self) -> Union[float, sympy.Symbol]:
        """Phi parameter (controlled-phase)."""

class PhasedFSimGate(Gate):
    """Phased fermionic simulation gate."""
    
    def __init__(self, *, theta: Union[float, sympy.Symbol],
                 zeta: Union[float, sympy.Symbol] = 0,
                 chi: Union[float, sympy.Symbol] = 0,
                 gamma: Union[float, sympy.Symbol] = 0,
                 phi: Union[float, sympy.Symbol] = 0) -> None:
        """Initialize phased FSim gate."""

class PhasedISwapPowGate(Gate):
    """Phased iSWAP power gate."""
    
    def __init__(self, *, phase_exponent: Union[float, sympy.Symbol],
                 exponent: Union[float, sympy.Symbol] = 1.0) -> None:
        """Initialize phased iSWAP power gate."""

Givens Rotations and Special Gates

def givens(angle_rads: Union[float, sympy.Symbol]) -> FSimGate:
    """Givens rotation gate."""
    
class TwoQubitDiagonalGate(Gate):
    """Two-qubit diagonal unitary gate."""
    
    def __init__(self, diag_angles_radians: Sequence[Union[float, sympy.Symbol]]) -> None:
        """Initialize with diagonal angles."""

Three-Qubit Gates

Toffoli and Controlled-Controlled Gates

class CCXPowGate(Gate):
    """Controlled-controlled-X gate (Toffoli): CCX^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize CCX power gate."""

class CCZPowGate(Gate):
    """Controlled-controlled-Z gate: CCZ^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize CCZ power gate."""

class CCNotPowGate(CCXPowGate):
    """Alias for CCXPowGate."""

class CSwapGate(Gate):
    """Controlled SWAP gate (Fredkin gate)."""
    
    def __init__(self) -> None:
        """Initialize controlled SWAP gate."""

# Common instances
CCX: CCXPowGate      # Controlled-controlled-X (Toffoli)
TOFFOLI: CCXPowGate  # Alias for CCX
CCZ: CCZPowGate      # Controlled-controlled-Z
CCNOT: CCNotPowGate  # Alias for CCX
CSWAP: CSwapGate     # Controlled SWAP (Fredkin)
FREDKIN: CSwapGate   # Alias for CSWAP

Three-Qubit Diagonal Gates

class ThreeQubitDiagonalGate(Gate):
    """Three-qubit diagonal unitary gate."""
    
    def __init__(self, diag_angles_radians: Sequence[Union[float, sympy.Symbol]]) -> None:
        """Initialize with 8 diagonal angles."""

Parity Gates

Parity interaction gates for quantum simulation.

class XXPowGate(EigenGate):
    """XX parity interaction gate: XX^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize XX power gate."""

class YYPowGate(EigenGate):
    """YY parity interaction gate: YY^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize YY power gate."""

class ZZPowGate(EigenGate):
    """ZZ parity interaction gate: ZZ^exponent."""
    
    def __init__(self, *, exponent: Union[float, sympy.Symbol] = 1.0, global_shift: float = 0.0) -> None:
        """Initialize ZZ power gate."""

XX: XXPowGate  # XX parity gate
YY: YYPowGate  # YY parity gate  
ZZ: ZZPowGate  # ZZ parity gate

Mølmer-Sørensen Gate

class MSGate(Gate):
    """Mølmer-Sørensen gate for trapped ion systems."""
    
    def __init__(self, num_qubits: int, *, rads: Union[float, sympy.Symbol] = np.pi/4) -> None:
        """Initialize MS gate."""

def ms(*qubits: 'cirq.Qid', rads: Union[float, sympy.Symbol] = np.pi/4) -> MSGate:
    """Mølmer-Sørensen gate function."""

Measurement Gates

Computational Basis Measurements

class MeasurementGate(Gate):
    """Computational basis measurement."""
    
    def __init__(self, num_qubits: Optional[int] = None, 
                 key: Union[str, 'cirq.MeasurementKey'] = '', 
                 invert_mask: Union[None, int, Sequence[bool], Sequence[int]] = None,
                 qid_shape: Optional[Tuple[int, ...]] = None) -> None:
        """Initialize measurement gate."""
        
    @property
    def key(self) -> str:
        """Measurement key for storing results."""
        
    @property
    def invert_mask(self) -> Tuple[bool, ...]:
        """Mask indicating which qubits to invert before measurement."""
        
    def with_bits_flipped(self, *bit_positions: int) -> 'MeasurementGate':
        """Return measurement with flipped invert mask."""

def measure(*qubits: 'cirq.Qid', key: Union[str, 'cirq.MeasurementKey'] = None, 
           invert_mask: Union[None, int, Sequence[bool], Sequence[int]] = None) -> Operation:
    """Measure qubits in computational basis."""
    
def measure_each(*qubits: 'cirq.Qid', key_func: Callable[['cirq.Qid'], str] = str) -> List[Operation]:
    """Measure each qubit individually."""

# Shorthand
M = measure

Pauli Basis Measurements

class PauliMeasurementGate(Gate):
    """Pauli basis measurement."""
    
    def __init__(self, observable: 'cirq.PauliString', 
                 key: Union[str, 'cirq.MeasurementKey'] = '') -> None:
        """Initialize Pauli measurement."""
        
    @property
    def observable(self) -> 'cirq.PauliString':
        """Pauli string to measure."""

def measure_single_paulistring(pauli_string: 'cirq.PauliString', 
                              key: Union[str, 'cirq.MeasurementKey'] = None) -> List[Operation]:
    """Measure a single Pauli string."""
    
def measure_paulistring_terms(pauli_strings: Sequence['cirq.PauliString'],
                             key: Union[str, 'cirq.MeasurementKey'] = None) -> List[Operation]:
    """Measure multiple Pauli string terms."""

Noise Channels

Quantum noise channels for realistic NISQ simulation.

Depolarizing Channels

class DepolarizingChannel(Gate):
    """Depolarizing noise channel."""
    
    def __init__(self, p: Union[float, sympy.Symbol], n_qubits: int = None) -> None:
        """Initialize depolarizing channel with error probability p."""
        
    @property
    def p(self) -> Union[float, sympy.Symbol]:
        """Depolarizing probability."""

class AsymmetricDepolarizingChannel(Gate):
    """Asymmetric depolarizing noise channel."""
    
    def __init__(self, p_x: Union[float, sympy.Symbol] = 0.0,
                 p_y: Union[float, sympy.Symbol] = 0.0, 
                 p_z: Union[float, sympy.Symbol] = 0.0) -> None:
        """Initialize with individual Pauli error rates."""

def depolarize(p: Union[float, sympy.Symbol], n_qubits: int = None) -> DepolarizingChannel:
    """Create depolarizing channel."""
    
def asymmetric_depolarize(p_x: Union[float, sympy.Symbol] = 0.0,
                         p_y: Union[float, sympy.Symbol] = 0.0,
                         p_z: Union[float, sympy.Symbol] = 0.0) -> AsymmetricDepolarizingChannel:
    """Create asymmetric depolarizing channel."""

Single-Qubit Error Channels

class BitFlipChannel(Gate):
    """Bit flip noise channel (X error)."""
    
    def __init__(self, p: Union[float, sympy.Symbol]) -> None:
        """Initialize bit flip channel."""

class PhaseFlipChannel(Gate):
    """Phase flip noise channel (Z error)."""
    
    def __init__(self, p: Union[float, sympy.Symbol]) -> None:
        """Initialize phase flip channel."""

class PhaseDampingChannel(Gate):
    """Phase damping noise channel."""
    
    def __init__(self, gamma: Union[float, sympy.Symbol]) -> None:
        """Initialize phase damping channel."""

def bit_flip(p: Union[float, sympy.Symbol]) -> BitFlipChannel:
    """Create bit flip channel."""
    
def phase_flip(p: Union[float, sympy.Symbol]) -> PhaseFlipChannel:
    """Create phase flip channel."""
    
def phase_damp(gamma: Union[float, sympy.Symbol]) -> PhaseDampingChannel:
    """Create phase damping channel."""

Amplitude Damping Channels

class AmplitudeDampingChannel(Gate):
    """Amplitude damping noise channel."""
    
    def __init__(self, gamma: Union[float, sympy.Symbol]) -> None:
        """Initialize amplitude damping channel."""

class GeneralizedAmplitudeDampingChannel(Gate):
    """Generalized amplitude damping noise channel."""
    
    def __init__(self, p: Union[float, sympy.Symbol], 
                 gamma: Union[float, sympy.Symbol]) -> None:
        """Initialize generalized amplitude damping channel."""

def amplitude_damp(gamma: Union[float, sympy.Symbol]) -> AmplitudeDampingChannel:
    """Create amplitude damping channel."""
    
def generalized_amplitude_damp(p: Union[float, sympy.Symbol],
                              gamma: Union[float, sympy.Symbol]) -> GeneralizedAmplitudeDampingChannel:
    """Create generalized amplitude damping channel."""

Advanced Noise Channels

class ResetChannel(Gate):
    """Reset to specific state."""
    
    def __init__(self, dimension: int = 2, reset_state: int = 0) -> None:
        """Initialize reset channel."""

class StatePreparationChannel(Gate):
    """State preparation channel."""
    
    def __init__(self, target_state: Union[int, np.ndarray],
                 num_qubits: Optional[int] = None) -> None:
        """Initialize state preparation channel."""

class KrausChannel(Gate):
    """General Kraus noise channel."""
    
    def __init__(self, kraus_ops: Sequence[np.ndarray]) -> None:
        """Initialize with Kraus operators."""

class MixedUnitaryChannel(Gate):
    """Mixed unitary noise channel."""
    
    def __init__(self, mixture: Dict['cirq.Gate', float]) -> None:
        """Initialize with gate mixture."""

class RandomGateChannel(Gate):
    """Random gate noise channel."""
    
    def __init__(self, sub_gate: 'cirq.Gate', probability: float = 1.0) -> None:
        """Initialize random gate channel."""

Reset Operations

class ResetChannel(Gate):
    """Reset qubits to |0⟩ state."""
    
    def __init__(self, dimension: int = 2, reset_state: int = 0) -> None:
        """Initialize reset channel."""

def reset(*qubits: 'cirq.Qid') -> List[Operation]:
    """Reset qubits to |0⟩ state."""
    
def reset_each(*qubits: 'cirq.Qid') -> List[Operation]:
    """Reset each qubit individually to |0⟩."""

Matrix and Custom Gates

MatrixGate

Define gates by their unitary matrices.

class MatrixGate(Gate):
    """Gate defined by unitary matrix."""
    
    def __init__(self, matrix: np.ndarray, *, name: str = None, 
                 qid_shape: Optional[Tuple[int, ...]] = None) -> None:
        """Initialize gate with unitary matrix."""
        
    @property  
    def matrix(self) -> np.ndarray:
        """Unitary matrix of the gate."""

DiagonalGate

Gates with diagonal unitary matrices.

class DiagonalGate(Gate):
    """Diagonal unitary gate."""
    
    def __init__(self, diag_angles_radians: Sequence[Union[float, sympy.Symbol]]) -> None:
        """Initialize with diagonal phases."""
        
    @property
    def diag_angles_radians(self) -> Tuple[Union[float, sympy.Symbol], ...]:
        """Diagonal angles in radians."""

Controlled Operations

ControlledGate

Create controlled versions of any gate.

class ControlledGate(Gate):
    """Controlled version of any gate."""
    
    def __init__(self, sub_gate: 'cirq.Gate',
                 num_controls: Optional[int] = None,
                 control_values: Optional[Sequence[Union[int, Collection[int]]]] = None,
                 control_qid_shape: Optional[Tuple[int, ...]] = None) -> None:
        """Initialize controlled gate."""
        
    @property
    def sub_gate(self) -> 'cirq.Gate':
        """The controlled gate."""
        
    @property
    def num_controls(self) -> int:
        """Number of control qubits."""

class ControlledOperation(Operation):
    """Controlled version of any operation."""
    
    def __init__(self, controls: Sequence['cirq.Qid'],
                 sub_operation: Operation,
                 control_values: Optional[Sequence[Union[int, Collection[int]]]] = None) -> None:
        """Initialize controlled operation."""

Classically Controlled Operations

class ClassicallyControlledOperation(Operation):
    """Operation controlled by classical measurement results."""
    
    def __init__(self, sub_operation: Operation,
                 conditions: Sequence['cirq.Condition']) -> None:
        """Initialize classically controlled operation."""

Pauli Strings and Operations

Pauli Operators

class Pauli(Gate):
    """Single-qubit Pauli operator."""
    
    def __init__(self, *, _index: Optional[int] = None, name: Optional[str] = None) -> None:
        """Initialize Pauli operator."""
        
    @classmethod
    def by_index(cls, index: int) -> 'Pauli':
        """Get Pauli by index (0=I, 1=X, 2=Y, 3=Z)."""
        
    @classmethod
    def by_relative_index(cls, pauli: 'Pauli', relative_index: int) -> 'Pauli':
        """Get Pauli by relative index."""

# Pauli constants (also available as gate instances)
pauli_gates = [I, X, Y, Z]  # Index-based access

PauliString

Products of Pauli operators acting on multiple qubits.

class PauliString:
    """Product of Pauli operators on multiple qubits."""
    
    def __init__(self, qubit_pauli_map: Optional[Dict['cirq.Qid', 'cirq.Pauli']] = None,
                 coefficient: Union[int, float, complex] = 1) -> None:
        """Initialize Pauli string."""
        
    @property
    def coefficient(self) -> Union[int, float, complex]:
        """Complex coefficient."""
        
    def keys(self) -> KeysView['cirq.Qid']:
        """Qubits with non-identity Pauli operators."""
        
    def values(self) -> ValuesView['cirq.Pauli']:
        """Pauli operators in the string."""
        
    def items(self) -> ItemsView['cirq.Qid', 'cirq.Pauli']:
        """(qubit, pauli) pairs."""
        
    def __getitem__(self, qubit: 'cirq.Qid') -> 'cirq.Pauli':
        """Get Pauli operator on given qubit."""
        
    def __mul__(self, other) -> Union['PauliString', 'PauliSum']:
        """Multiply with another Pauli string or scalar."""
        
    def __pow__(self, exponent) -> 'PauliStringPhasor':
        """Exponentiate Pauli string."""
        
    def conjugated_by(self, clifford: 'cirq.SupportsActOn') -> 'PauliString':
        """Conjugate by Clifford operation."""
        
    def expectation_from_state_vector(self, state: np.ndarray, qubit_map: Dict['cirq.Qid', int]) -> complex:
        """Calculate expectation value."""
        
    def zip_items(self, other: 'PauliString') -> Iterator[Tuple['cirq.Qid', Tuple['cirq.Pauli', 'cirq.Pauli']]]:
        """Zip items from two Pauli strings."""
        
    def zip_paulis(self, other: 'PauliString') -> Iterator[Tuple['cirq.Pauli', 'cirq.Pauli']]:
        """Zip Pauli operators from two strings."""

MutablePauliString

Mutable version of PauliString for efficient construction.

class MutablePauliString:
    """Mutable Pauli string for efficient construction."""
    
    def __init__(self, qubit_pauli_map: Optional[Dict['cirq.Qid', 'cirq.Pauli']] = None,
                 coefficient: Union[int, float, complex] = 1) -> None:
        """Initialize mutable Pauli string."""
        
    def __setitem__(self, qubit: 'cirq.Qid', pauli: 'cirq.Pauli') -> None:
        """Set Pauli operator on qubit."""
        
    def __delitem__(self, qubit: 'cirq.Qid') -> None:
        """Remove qubit from string."""
        
    def frozen(self) -> PauliString:
        """Convert to immutable PauliString."""

Dense Pauli Strings

Efficient representation for dense Pauli strings.

class BaseDensePauliString:
    """Base class for dense Pauli strings."""
    
    def __init__(self, pauli_mask: Sequence[int], coefficient: Union[int, float, complex] = 1) -> None:
        """Initialize with packed Pauli representation."""

class DensePauliString(BaseDensePauliString):
    """Dense representation of Pauli strings."""
    
    def on(self, *qubits: 'cirq.Qid') -> 'cirq.PauliString':
        """Apply to specific qubits, creating PauliString."""

class MutableDensePauliString(BaseDensePauliString):
    """Mutable dense Pauli string."""
    
    def __setitem__(self, index: int, pauli: Union['cirq.Pauli', int]) -> None:
        """Set Pauli at given index."""

Pauli String Operations

class PauliStringGateOperation(Operation):
    """Gate operation from Pauli string."""
    
    def __init__(self, pauli_string: PauliString) -> None:
        """Initialize from Pauli string."""

class SingleQubitPauliStringGateOperation(PauliStringGateOperation):
    """Single-qubit Pauli string operation."""

class PauliStringPhasor:
    """Exponential of a Pauli string: exp(i * exponent * pauli_string)."""
    
    def __init__(self, pauli_string: PauliString,
                 *, exponent_neg: Union[float, sympy.Symbol] = 1.0,
                 exponent_pos: Union[float, sympy.Symbol] = 1.0) -> None:
        """Initialize Pauli string phasor."""

class PauliStringPhasorGate(Gate):
    """Gate for Pauli string exponentials."""
    
    def __init__(self, pauli_string: PauliString,
                 *, exponent_neg: Union[float, sympy.Symbol] = 1.0,
                 exponent_pos: Union[float, sympy.Symbol] = 1.0) -> None:
        """Initialize Pauli string phasor gate."""

class PauliInteractionGate(Gate):
    """Pauli interaction gate."""
    
    def __init__(self, pauli0: 'cirq.Pauli', pauli1: 'cirq.Pauli',
                 *, rads: Union[float, sympy.Symbol] = np.pi) -> None:
        """Initialize Pauli interaction gate."""

Pauli Sums

class PauliSum:
    """Sum of Pauli strings."""
    
    def __init__(self, terms: Iterable[PauliString] = ()) -> None:
        """Initialize Pauli sum."""
        
    def __add__(self, other) -> 'PauliSum':
        """Add Pauli sums or strings."""
        
    def __mul__(self, other) -> 'PauliSum':
        """Multiply by scalar or other Pauli sum."""
        
    def expectation_from_state_vector(self, state: np.ndarray, qubit_map: Dict['cirq.Qid', int]) -> complex:
        """Calculate expectation value."""

class PauliSumExponential:
    """Exponential of a Pauli sum."""
    
    def __init__(self, pauli_sum: PauliSum, coefficient: Union[float, sympy.Symbol] = 1.0) -> None:
        """Initialize Pauli sum exponential."""

# Type aliases
PAULI_STRING_LIKE = Union[PauliString, str, Iterable[Tuple['cirq.Qid', Union['cirq.Pauli', str]]]]
PAULI_SUM_LIKE = Union[PauliSum, PauliString, str, int, float, complex]

Linear Combinations

Linear Combination of Gates

class LinearCombinationOfGates:
    """Linear combination of gates with complex coefficients."""
    
    def __init__(self, terms: Dict['cirq.Gate', Union[int, float, complex]]) -> None:
        """Initialize linear combination."""
        
    def __add__(self, other) -> 'LinearCombinationOfGates':
        """Add linear combinations."""
        
    def __mul__(self, scalar) -> 'LinearCombinationOfGates':
        """Multiply by scalar."""
        
    def matrix(self, qubits: Sequence['cirq.Qid']) -> np.ndarray:
        """Calculate matrix representation."""

class LinearCombinationOfOperations:
    """Linear combination of operations."""
    
    def __init__(self, terms: Dict[Operation, Union[int, float, complex]]) -> None:
        """Initialize linear combination of operations."""

Qubit Management

QubitManager Interface

class QubitManager:
    """Interface for managing ancilla qubits."""
    
    @abc.abstractmethod
    def qalloc(self, n: int = 1, dim: int = 2) -> List['cirq.Qid']:
        """Allocate n qubits of given dimension."""
        
    @abc.abstractmethod
    def qfree(self, qids: List['cirq.Qid']) -> None:
        """Free previously allocated qubits."""

class SimpleQubitManager(QubitManager):
    """Simple implementation of qubit manager."""
    
    def __init__(self) -> None:
        """Initialize simple qubit manager."""

class GreedyQubitManager(QubitManager):
    """Greedy ancilla allocation strategy."""
    
    def __init__(self, prefix: str = "ancilla", maximize_reuse: bool = False) -> None:
        """Initialize greedy qubit manager."""

class BorrowableQubit:
    """Qubit that can be borrowed temporarily."""
    
    def __init__(self, qid: 'cirq.Qid') -> None:
        """Initialize borrowable qubit."""

class CleanQubit:
    """Clean ancilla qubit guaranteed to be in |0⟩ state."""
    
    def __init__(self, qid: 'cirq.Qid') -> None:
        """Initialize clean qubit."""

Gate Collections and Sets

GateFamily

Collections of related gates for compilation and optimization.

class GateFamily:
    """Collection of related gates."""
    
    def __init__(self, gate: 'cirq.Gate', 
                 name: Optional[str] = None,
                 description: Optional[str] = None,
                 tags_to_accept: Sequence = (),
                 tags_to_ignore: Sequence = ()) -> None:
        """Initialize gate family."""
        
    def predicate(self, gate: 'cirq.Gate') -> bool:
        """Check if gate belongs to this family."""

class Gateset:
    """Set of allowed gates for compilation."""
    
    def __init__(self, *gates: Union['cirq.Gate', GateFamily],
                 name: Optional[str] = None,
                 unroll_circuit_op: bool = True) -> None:
        """Initialize gateset."""
        
    def validate(self, circuit_or_operation: Union['cirq.AbstractCircuit', Operation]) -> None:
        """Validate circuit against gateset."""
        
    def __contains__(self, item) -> bool:
        """Check if gate/operation is in gateset."""

class AnyUnitaryGateFamily(GateFamily):
    """Family accepting any unitary gate."""
    
    def __init__(self, num_qubits: int) -> None:
        """Initialize for given number of qubits."""

class AnyIntegerPowerGateFamily(GateFamily):
    """Family accepting integer powers of a gate."""
    
    def __init__(self, gate: 'cirq.EigenGate') -> None:
        """Initialize for eigen gate."""

class ParallelGateFamily(GateFamily):
    """Family of parallel gate applications."""
    
    def __init__(self, gate: 'cirq.Gate') -> None:
        """Initialize for given gate."""

Operation Trees and Utilities

Operation Tree Types

OP_TREE = Union[Operation, Iterable['OP_TREE']]
"""Type representing nested operations."""

def flatten_op_tree(root: OP_TREE, preserve_moments: bool = True) -> Iterator[Union[Operation, 'cirq.Moment']]:
    """Flatten nested operation tree."""
    
def flatten_to_ops(root: OP_TREE) -> List[Operation]:
    """Flatten to operations only."""
    
def flatten_to_ops_or_moments(root: OP_TREE) -> List[Union[Operation, 'cirq.Moment']]:
    """Flatten to operations or moments."""
    
def freeze_op_tree(root: OP_TREE) -> Tuple[Union[Operation, 'cirq.Moment'], ...]:
    """Create immutable operation tree."""
    
def transform_op_tree(root: OP_TREE, 
                     op_transformation: Callable[[Operation], OP_TREE] = lambda e: e,
                     moment_transformation: Callable[['cirq.Moment'], OP_TREE] = lambda e: e,
                     preserve_moments: bool = True) -> OP_TREE:
    """Transform operation tree with given functions."""

Special Operations

class ParallelGate(Gate):
    """Parallel application of a gate to multiple qubit sets."""
    
    def __init__(self, sub_gate: 'cirq.Gate', num_copies: int) -> None:
        """Initialize parallel gate."""

def parallel_gate_op(gate: 'cirq.Gate', qubits: Sequence[Sequence['cirq.Qid']]) -> Operation:
    """Create parallel gate operation."""

class WaitGate(Gate):
    """Idle/wait operation for specified duration."""
    
    def __init__(self, duration: 'cirq.Duration', num_qubits: int = 1) -> None:
        """Initialize wait gate."""

def wait(*qubits: 'cirq.Qid', nanos: Union[float, int] = None) -> Operation:
    """Create wait operation."""

Tags

Metadata tags for operations.

class VirtualTag:
    """Tag for virtual/logical operations."""
    
    def __init__(self) -> None:
        """Initialize virtual tag."""

class RoutingSwapTag:
    """Tag for routing SWAP operations."""
    
    def __init__(self) -> None:
        """Initialize routing SWAP tag."""

Special Purpose Gates

Arithmetic and Boolean Gates

class ArithmeticGate(Gate):
    """Arithmetic operation gate."""
    
    def registers(self) -> Dict[str, Sequence[int]]:
        """Register definitions for arithmetic operations."""

class BooleanHamiltonianGate(Gate):
    """Boolean Hamiltonian gate."""
    
    def __init__(self, parameter_names: Sequence[str],
                 boolean_strs: Sequence[str],
                 theta: Union[float, sympy.Symbol] = sympy.Symbol('theta')) -> None:
        """Initialize Boolean Hamiltonian gate."""

Quantum Fourier Transform

class QuantumFourierTransformGate(Gate):
    """Quantum Fourier transform gate."""
    
    def __init__(self, num_qubits: int, *, without_reverse: bool = False) -> None:
        """Initialize QFT gate."""

def qft(*qubits: 'cirq.Qid', without_reverse: bool = False, inverse: bool = False) -> List[Operation]:
    """Quantum Fourier transform operation."""

Phase Gradient Gate

class PhaseGradientGate(Gate):
    """Phase gradient gate for QFT implementation."""
    
    def __init__(self, num_qubits: int, *, exponent: Union[float, sympy.Symbol] = 1.0) -> None:
        """Initialize phase gradient gate."""

Uniform Superposition

class UniformSuperpositionGate(Gate):
    """Gate that creates uniform superposition over computational basis states."""
    
    def __init__(self, num_qubits: int) -> None:
        """Initialize uniform superposition gate."""

Usage Examples

Basic Gate Operations

import cirq
import numpy as np

# Single-qubit operations
q = cirq.LineQubit(0)
circuit = cirq.Circuit([
    cirq.H(q),           # Hadamard
    cirq.X(q)**0.5,      # √X gate
    cirq.rz(np.pi/4)(q), # Z rotation
])

# Multi-qubit operations  
q0, q1 = cirq.LineQubit.range(2)
circuit.append([
    cirq.CNOT(q0, q1),          # CNOT gate
    cirq.CZ(q0, q1)**0.5,       # √CZ gate
    cirq.SWAP(q0, q1),          # SWAP gate
])

print("Circuit:")
print(circuit)

Custom Gates from Matrices

import cirq
import numpy as np

# Define custom single-qubit gate
custom_matrix = np.array([[1, 1], [1, -1]]) / np.sqrt(2)  # Hadamard matrix
custom_gate = cirq.MatrixGate(custom_matrix, name="CustomH")

# Apply to qubit
q = cirq.LineQubit(0)
op = custom_gate(q)
print(f"Custom gate operation: {op}")

# Two-qubit diagonal gate
diagonal_angles = [0, np.pi/4, np.pi/2, 3*np.pi/4]
diag_gate = cirq.TwoQubitDiagonalGate(diagonal_angles)

q0, q1 = cirq.LineQubit.range(2)
circuit = cirq.Circuit(diag_gate(q0, q1))

Controlled Operations

import cirq

# Create controlled version of any gate
target = cirq.LineQubit(0)
control = cirq.LineQubit(1)

# Controlled Hadamard
controlled_h = cirq.H.controlled()
ch_op = controlled_h(control, target)

# Multi-controlled gate
controls = cirq.LineQubit.range(3)
target = cirq.LineQubit(3)
ccch = cirq.H.controlled(num_controls=3)
ccch_op = ccch(*controls, target)

print(f"Controlled H: {ch_op}")
print(f"Triple-controlled H: {ccch_op}")

Pauli String Operations

import cirq

# Create Pauli string
qubits = cirq.LineQubit.range(3)
pauli_string = cirq.PauliString({
    qubits[0]: cirq.X,
    qubits[1]: cirq.Y, 
    qubits[2]: cirq.Z
}, coefficient=0.5)

print(f"Pauli string: {pauli_string}")

# Exponentiate to create rotation
rotation_angle = np.pi/4
phasor = pauli_string ** rotation_angle
phasor_gate = cirq.PauliStringPhasorGate(pauli_string, exponent_neg=rotation_angle)

# Add to circuit
circuit = cirq.Circuit(phasor_gate(*qubits))

Noise Channel Application

import cirq

# Build clean circuit
qubits = cirq.LineQubit.range(2)
circuit = cirq.Circuit([
    cirq.H(qubits[0]),
    cirq.CNOT(qubits[0], qubits[1])
])

# Add noise after each gate
noisy_circuit = cirq.Circuit()
for moment in circuit:
    noisy_circuit.append(moment)
    # Add depolarizing noise after each operation
    for op in moment:
        for qubit in op.qubits:
            noisy_circuit.append(cirq.depolarize(0.01)(qubit))

print("Noisy circuit:")
print(noisy_circuit)

This comprehensive documentation covers the extensive gate and operation library in Cirq, providing the foundation for quantum circuit construction and NISQ simulation.

Install with Tessl CLI

npx tessl i tessl/pypi-cirq

docs

circuits.md

devices.md

index.md

linalg.md

ops.md

protocols.md

qis.md

remaining-modules.md

sim.md

study.md

transformers.md

tile.json