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

Additional Modules

Name: tessl/pypi-cirq
Author: tessl

This document covers the remaining modules in cirq: value utilities, visualization, workflow management, experiments, and interoperability.

Value Types and Utilities

Duration and Time

class Duration:
    """Represents a time duration."""
    
    def __init__(self, *, picos: int = 0, nanos: int = 0, 
                 micros: int = 0, millis: int = 0) -> None:
        """Initialize duration from various time units."""
        
    @property
    def total_picos(self) -> int:
        """Total duration in picoseconds."""
        
    @property
    def total_nanos(self) -> float:
        """Total duration in nanoseconds."""
        
    def __add__(self, other: 'Duration') -> 'Duration':
        """Add durations."""

class Timestamp:
    """Represents a point in time."""
    
    def __init__(self, *, picos: int = 0, nanos: int = 0) -> None:
        """Initialize timestamp."""

DURATION_LIKE = Union[Duration, float, int]

Measurement Keys and Classical Data

class MeasurementKey:
    """Identifies measurement results."""
    
    def __init__(self, name: str, path: Tuple[str, ...] = ()) -> None:
        """Initialize measurement key."""

class ClassicalDataStore:
    """Interface for classical data storage."""
    
    def copy(self) -> 'ClassicalDataStore':
        """Create copy of data store."""

class LinearDict:
    """Dictionary with linear operations."""
    
    def __init__(self, terms: Dict[Any, Union[int, float, complex]] = None) -> None:
        """Initialize linear dictionary."""

Product States

class ProductState:
    """Represents a product state."""
    
    def __init__(self, states: Dict['cirq.Qid', int]) -> None:
        """Initialize product state."""

# Standard states
KET_PLUS: ProductState    # |+⟩ state
KET_MINUS: ProductState   # |−⟩ state  
KET_IMAG: ProductState    # |i⟩ state
KET_MINUS_IMAG: ProductState  # |−i⟩ state
KET_ZERO: ProductState    # |0⟩ state
KET_ONE: ProductState     # |1⟩ state
PAULI_STATES: Tuple[ProductState, ...]  # All Pauli eigenstates

Visualization Tools

Heatmaps

class Heatmap:
    """General heatmap visualization."""
    
    def __init__(self, value_map: Mapping[Tuple[int, ...], float]) -> None:
        """Initialize heatmap with value mapping."""
        
    def plot(self, ax: 'matplotlib.axes.Axes' = None) -> 'matplotlib.axes.Axes':
        """Plot heatmap."""

class TwoQubitInteractionHeatmap(Heatmap):
    """Heatmap for two-qubit interactions."""
    
    def __init__(self, interaction_map: Mapping[Tuple['cirq.Qid', 'cirq.Qid'], float]) -> None:
        """Initialize two-qubit interaction heatmap."""

State and Result Visualization

def plot_state_histogram(result: 'cirq.Result', 
                        ax: 'matplotlib.axes.Axes' = None) -> 'matplotlib.axes.Axes':
    """Plot histogram of measurement results."""

def get_state_histogram(result: 'cirq.Result') -> Dict[int, int]:
    """Get histogram data from measurement results."""

def integrated_histogram(data: Sequence[int], 
                        max_count: Optional[int] = None) -> Dict[int, int]:
    """Create integrated histogram."""

def plot_density_matrix(matrix: np.ndarray, 
                       ax: 'matplotlib.axes.Axes' = None) -> None:
    """Visualize density matrix as bar chart."""

def relative_luminance(rgb: Tuple[float, float, float]) -> float:
    """Calculate relative luminance for colors."""

Workflow and Sampling

Sampler Framework

class Sampler:
    """Abstract base class for samplers."""
    
    def run(self, program: 'cirq.CIRCUIT_LIKE',
           param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
           repetitions: int = 1) -> 'cirq.Result':
        """Run circuit and return measurement results."""

class ZerosSampler(Sampler):
    """Sampler that returns all-zero results."""
    
    def __init__(self) -> None:
        """Initialize zeros sampler."""

Collection Framework

class Collector:
    """Abstract base for result collection."""
    
    def collect(self, circuit: 'cirq.Circuit', 
               repetitions: int,
               sweep: 'cirq.Sweepable' = None) -> Any:
        """Collect results from circuit execution."""

class CircuitSampleJob:
    """Job for circuit sampling."""
    
    def __init__(self, circuit: 'cirq.Circuit',
                 repetitions: int = 1,
                 sweep: 'cirq.Sweepable' = None) -> None:
        """Initialize sampling job."""

class PauliSumCollector(Collector):
    """Collector for Pauli sum measurements."""
    
    def __init__(self, circuit: 'cirq.Circuit',
                 observables: List['cirq.PauliSum'],
                 sampler: 'cirq.Sampler') -> None:
        """Initialize Pauli sum collector."""

Observable Management

class InitObsSetting:
    """Initial observable setting."""
    
    def __init__(self, observable: 'cirq.PauliString') -> None:
        """Initialize observable setting."""

def observables_to_settings(observables: Sequence['cirq.PauliString']) -> List[InitObsSetting]:
    """Convert observables to settings."""

def group_settings_greedy(settings: Sequence[InitObsSetting]) -> List[List[InitObsSetting]]:
    """Group settings using greedy algorithm."""

Experiments and Characterization

Randomized Benchmarking

def single_qubit_randomized_benchmarking(sampler: 'cirq.Sampler',
                                       qubit: 'cirq.Qid',
                                       use_cliffords: bool = True) -> 'RandomizedBenchMarkResult':
    """Single-qubit randomized benchmarking experiment."""

def two_qubit_randomized_benchmarking(sampler: 'cirq.Sampler',
                                    qubits: Sequence['cirq.Qid']) -> 'RandomizedBenchMarkResult':
    """Two-qubit randomized benchmarking experiment."""

class RandomizedBenchMarkResult:
    """Result of randomized benchmarking experiment."""
    
    def __init__(self, decay_constant: float, 
                 confidence_interval: Tuple[float, float]) -> None:
        """Initialize RB result."""

Fidelity Estimation

def xeb_fidelity(circuit_results: Dict['cirq.Circuit', List[int]],
               simulated_probs: Dict['cirq.Circuit', np.ndarray]) -> float:
    """Cross-entropy benchmarking fidelity."""

def linear_xeb_fidelity(measured_probabilities: Sequence[float],
                       ideal_probabilities: Sequence[float]) -> float:
    """Linear XEB fidelity calculation."""

def log_xeb_fidelity_from_probabilities(hilbert_space_dimension: int,
                                       measured_probabilities: Sequence[float]) -> float:
    """Logarithmic XEB fidelity from probabilities."""

def hog_score_xeb_fidelity_from_probabilities(measured_probabilities: Sequence[float],
                                            uniform_probabilities: Sequence[float]) -> float:
    """HOG score XEB fidelity calculation."""

State Tomography

def single_qubit_state_tomography(sampler: 'cirq.Sampler',
                                qubit: 'cirq.Qid',
                                circuit: 'cirq.Circuit') -> 'TomographyResult':
    """Single-qubit state tomography experiment."""

def two_qubit_state_tomography(sampler: 'cirq.Sampler',
                             qubits: Sequence['cirq.Qid'],
                             circuit: 'cirq.Circuit') -> 'TomographyResult':
    """Two-qubit state tomography experiment."""

class TomographyResult:
    """Result of quantum tomography experiment."""
    
    def __init__(self, reconstructed_state: np.ndarray,
                 fidelity: float) -> None:
        """Initialize tomography result."""

Coherence Time Measurements

def t1_decay(sampler: 'cirq.Sampler',
           qubit: 'cirq.Qid',
           max_delay: 'cirq.Duration') -> 'T1DecayResult':
    """T1 decay time measurement."""

def t2_decay(sampler: 'cirq.Sampler', 
           qubit: 'cirq.Qid',
           max_delay: 'cirq.Duration') -> 'T2DecayResult':
    """T2 dephasing time measurement."""

class T1DecayResult:
    """T1 decay measurement result."""
    
    def __init__(self, t1_time: 'cirq.Duration',
                 fit_quality: float) -> None:
        """Initialize T1 result."""

class T2DecayResult:
    """T2 decay measurement result."""
    
    def __init__(self, t2_time: 'cirq.Duration',
                 fit_quality: float) -> None:
        """Initialize T2 result."""

Readout Error Characterization

def estimate_single_qubit_readout_errors(sampler: 'cirq.Sampler',
                                       qubit: 'cirq.Qid') -> 'SingleQubitReadoutCalibrationResult':
    """Estimate single-qubit readout errors."""

def measure_confusion_matrix(sampler: 'cirq.Sampler',
                           qubits: Sequence['cirq.Qid']) -> 'TensoredConfusionMatrices':
    """Measure readout confusion matrix."""

class SingleQubitReadoutCalibrationResult:
    """Single-qubit readout calibration result."""
    
    def __init__(self, zero_state_errors: Tuple[float, float],
                 one_state_errors: Tuple[float, float]) -> None:
        """Initialize readout calibration result."""

class TensoredConfusionMatrices:
    """Tensor product of confusion matrices."""
    
    def __init__(self, confusion_matrices: Sequence[np.ndarray]) -> None:
        """Initialize tensored confusion matrices."""

Interoperability

Quirk Integration

def quirk_json_to_circuit(json_text: str) -> 'cirq.Circuit':
    """Convert Quirk JSON to Cirq circuit.
    
    Args:
        json_text: Quirk circuit as JSON string
        
    Returns:
        Equivalent Cirq circuit
    """

def quirk_url_to_circuit(url: str) -> 'cirq.Circuit':
    """Convert Quirk URL to Cirq circuit.
    
    Args:
        url: Quirk circuit URL
        
    Returns:
        Equivalent Cirq circuit
    """

Neutral Atoms Support

def is_native_neutral_atom_gate(gate: 'cirq.Gate') -> bool:
    """Check if gate is native to neutral atom systems."""

def is_native_neutral_atom_op(operation: 'cirq.Operation') -> bool:
    """Check if operation is native to neutral atoms."""

Usage Examples

Duration and Timing

import cirq

# Create durations
duration1 = cirq.Duration(nanos=50)  # 50 ns
duration2 = cirq.Duration(micros=1)  # 1 μs

print(f"Duration 1: {duration1.total_nanos} ns")
print(f"Duration 2: {duration2.total_nanos} ns")

# Add durations
total_duration = duration1 + duration2
print(f"Total: {total_duration.total_nanos} ns")

# Create timestamp
timestamp = cirq.Timestamp(nanos=100)
print(f"Timestamp: {timestamp}")

Measurement Results Visualization

import cirq
import matplotlib.pyplot as plt

# Create circuit and get results
qubits = cirq.LineQubit.range(2)
circuit = cirq.Circuit([
    cirq.H(qubits[0]),
    cirq.CNOT(qubits[0], qubits[1]),
    cirq.measure(*qubits, key='bell_pair')
])

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

# Plot histogram
fig, ax = plt.subplots()
cirq.plot_state_histogram(result, ax=ax)
ax.set_title('Bell State Measurement Results')
plt.show()

# Get histogram data
histogram = cirq.get_state_histogram(result)
print(f"Measurement histogram: {histogram}")

Working with Product States

import cirq

# Use predefined product states
qubits = cirq.LineQubit.range(2)

# Create circuit preparing |+0⟩ state
circuit = cirq.Circuit([
    cirq.H(qubits[0])  # |0⟩ → |+⟩
    # qubits[1] stays in |0⟩
])

print("Pauli eigenstates:")
for i, state in enumerate(cirq.PAULI_STATES):
    print(f"  State {i}: {state}")

# Use in circuit initialization
initial_state = {qubits[0]: 0, qubits[1]: 1}  # |01⟩
product_state = cirq.ProductState(initial_state)
print(f"Product state |01⟩: {product_state}")

Simple Experiments

import cirq
import numpy as np

# Simulate a simple RB experiment
print("=== Randomized Benchmarking ===")
simulator = cirq.Simulator()
qubit = cirq.LineQubit(0)

# Create mock RB result (in practice, use real hardware sampler)
mock_decay = 0.02  # 2% error per Clifford
mock_rb_result = cirq.RandomizedBenchMarkResult(
    decay_constant=mock_decay,
    confidence_interval=(0.015, 0.025)
)

print(f"RB decay constant: {mock_rb_result.decay_constant}")
print(f"Confidence interval: {mock_rb_result.confidence_interval}")

# XEB fidelity calculation
print("\n=== XEB Fidelity ===")
# Mock data
measured_probs = [0.24, 0.26, 0.23, 0.27]  # Measured probabilities
ideal_probs = [0.25, 0.25, 0.25, 0.25]     # Ideal uniform probabilities

linear_fidelity = cirq.linear_xeb_fidelity(measured_probs, ideal_probs)
print(f"Linear XEB fidelity: {linear_fidelity:.4f}")

Interoperability Examples

import cirq

# Convert from Quirk (example JSON)
quirk_json = '''
{
    "cols": [
        ["H"],
        ["•", "X"]
    ]
}
'''

try:
    # This would work with actual Quirk integration
    # quirk_circuit = cirq.quirk_json_to_circuit(quirk_json)
    # print("Converted Quirk circuit:")
    # print(quirk_circuit)
    print("Quirk integration available via quirk_json_to_circuit()")
except:
    print("Quirk integration requires proper JSON format")

# Check neutral atom compatibility
h_gate = cirq.H
x_gate = cirq.X

print(f"H gate native to neutral atoms: {cirq.is_native_neutral_atom_gate(h_gate)}")
print(f"X gate native to neutral atoms: {cirq.is_native_neutral_atom_gate(x_gate)}")

This completes the comprehensive documentation of cirq's additional modules, providing tools for timing, visualization, workflow management, quantum experiments, and integration with other quantum software platforms.

Install with Tessl CLI