0
# Additional Modules
1

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

4
## Value Types and Utilities
5

6
### Duration and Time
7

8
```python { .api }
9
class Duration:
10
    """Represents a time duration."""
11
    
12
    def __init__(self, *, picos: int = 0, nanos: int = 0, 
13
                 micros: int = 0, millis: int = 0) -> None:
14
        """Initialize duration from various time units."""
15
        
16
    @property
17
    def total_picos(self) -> int:
18
        """Total duration in picoseconds."""
19
        
20
    @property
21
    def total_nanos(self) -> float:
22
        """Total duration in nanoseconds."""
23
        
24
    def __add__(self, other: 'Duration') -> 'Duration':
25
        """Add durations."""
26

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

33
DURATION_LIKE = Union[Duration, float, int]
34
```
35

36
### Measurement Keys and Classical Data
37

38
```python { .api }
39
class MeasurementKey:
40
    """Identifies measurement results."""
41
    
42
    def __init__(self, name: str, path: Tuple[str, ...] = ()) -> None:
43
        """Initialize measurement key."""
44

45
class ClassicalDataStore:
46
    """Interface for classical data storage."""
47
    
48
    def copy(self) -> 'ClassicalDataStore':
49
        """Create copy of data store."""
50

51
class LinearDict:
52
    """Dictionary with linear operations."""
53
    
54
    def __init__(self, terms: Dict[Any, Union[int, float, complex]] = None) -> None:
55
        """Initialize linear dictionary."""
56
```
57

58
### Product States
59

60
```python { .api }
61
class ProductState:
62
    """Represents a product state."""
63
    
64
    def __init__(self, states: Dict['cirq.Qid', int]) -> None:
65
        """Initialize product state."""
66

67
# Standard states
68
KET_PLUS: ProductState    # |+⟩ state
69
KET_MINUS: ProductState   # |−⟩ state  
70
KET_IMAG: ProductState    # |i⟩ state
71
KET_MINUS_IMAG: ProductState  # |−i⟩ state
72
KET_ZERO: ProductState    # |0⟩ state
73
KET_ONE: ProductState     # |1⟩ state
74
PAULI_STATES: Tuple[ProductState, ...]  # All Pauli eigenstates
75
```
76

77
## Visualization Tools
78

79
### Heatmaps
80

81
```python { .api }
82
class Heatmap:
83
    """General heatmap visualization."""
84
    
85
    def __init__(self, value_map: Mapping[Tuple[int, ...], float]) -> None:
86
        """Initialize heatmap with value mapping."""
87
        
88
    def plot(self, ax: 'matplotlib.axes.Axes' = None) -> 'matplotlib.axes.Axes':
89
        """Plot heatmap."""
90

91
class TwoQubitInteractionHeatmap(Heatmap):
92
    """Heatmap for two-qubit interactions."""
93
    
94
    def __init__(self, interaction_map: Mapping[Tuple['cirq.Qid', 'cirq.Qid'], float]) -> None:
95
        """Initialize two-qubit interaction heatmap."""
96
```
97

98
### State and Result Visualization
99

100
```python { .api }
101
def plot_state_histogram(result: 'cirq.Result', 
102
                        ax: 'matplotlib.axes.Axes' = None) -> 'matplotlib.axes.Axes':
103
    """Plot histogram of measurement results."""
104

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

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

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

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

120
## Workflow and Sampling
121

122
### Sampler Framework
123

124
```python { .api }
125
class Sampler:
126
    """Abstract base class for samplers."""
127
    
128
    def run(self, program: 'cirq.CIRCUIT_LIKE',
129
           param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
130
           repetitions: int = 1) -> 'cirq.Result':
131
        """Run circuit and return measurement results."""
132

133
class ZerosSampler(Sampler):
134
    """Sampler that returns all-zero results."""
135
    
136
    def __init__(self) -> None:
137
        """Initialize zeros sampler."""
138
```
139

140
### Collection Framework
141

142
```python { .api }
143
class Collector:
144
    """Abstract base for result collection."""
145
    
146
    def collect(self, circuit: 'cirq.Circuit', 
147
               repetitions: int,
148
               sweep: 'cirq.Sweepable' = None) -> Any:
149
        """Collect results from circuit execution."""
150

151
class CircuitSampleJob:
152
    """Job for circuit sampling."""
153
    
154
    def __init__(self, circuit: 'cirq.Circuit',
155
                 repetitions: int = 1,
156
                 sweep: 'cirq.Sweepable' = None) -> None:
157
        """Initialize sampling job."""
158

159
class PauliSumCollector(Collector):
160
    """Collector for Pauli sum measurements."""
161
    
162
    def __init__(self, circuit: 'cirq.Circuit',
163
                 observables: List['cirq.PauliSum'],
164
                 sampler: 'cirq.Sampler') -> None:
165
        """Initialize Pauli sum collector."""
166
```
167

168
### Observable Management
169

170
```python { .api }
171
class InitObsSetting:
172
    """Initial observable setting."""
173
    
174
    def __init__(self, observable: 'cirq.PauliString') -> None:
175
        """Initialize observable setting."""
176

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

180
def group_settings_greedy(settings: Sequence[InitObsSetting]) -> List[List[InitObsSetting]]:
181
    """Group settings using greedy algorithm."""
182
```
183

184
## Experiments and Characterization
185

186
### Randomized Benchmarking
187

188
```python { .api }
189
def single_qubit_randomized_benchmarking(sampler: 'cirq.Sampler',
190
                                       qubit: 'cirq.Qid',
191
                                       use_cliffords: bool = True) -> 'RandomizedBenchMarkResult':
192
    """Single-qubit randomized benchmarking experiment."""
193

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

198
class RandomizedBenchMarkResult:
199
    """Result of randomized benchmarking experiment."""
200
    
201
    def __init__(self, decay_constant: float, 
202
                 confidence_interval: Tuple[float, float]) -> None:
203
        """Initialize RB result."""
204
```
205

206
### Fidelity Estimation
207

208
```python { .api }
209
def xeb_fidelity(circuit_results: Dict['cirq.Circuit', List[int]],
210
               simulated_probs: Dict['cirq.Circuit', np.ndarray]) -> float:
211
    """Cross-entropy benchmarking fidelity."""
212

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

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

221
def hog_score_xeb_fidelity_from_probabilities(measured_probabilities: Sequence[float],
222
                                            uniform_probabilities: Sequence[float]) -> float:
223
    """HOG score XEB fidelity calculation."""
224
```
225

226
### State Tomography
227

228
```python { .api }
229
def single_qubit_state_tomography(sampler: 'cirq.Sampler',
230
                                qubit: 'cirq.Qid',
231
                                circuit: 'cirq.Circuit') -> 'TomographyResult':
232
    """Single-qubit state tomography experiment."""
233

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

239
class TomographyResult:
240
    """Result of quantum tomography experiment."""
241
    
242
    def __init__(self, reconstructed_state: np.ndarray,
243
                 fidelity: float) -> None:
244
        """Initialize tomography result."""
245
```
246

247
### Coherence Time Measurements
248

249
```python { .api }
250
def t1_decay(sampler: 'cirq.Sampler',
251
           qubit: 'cirq.Qid',
252
           max_delay: 'cirq.Duration') -> 'T1DecayResult':
253
    """T1 decay time measurement."""
254

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

260
class T1DecayResult:
261
    """T1 decay measurement result."""
262
    
263
    def __init__(self, t1_time: 'cirq.Duration',
264
                 fit_quality: float) -> None:
265
        """Initialize T1 result."""
266

267
class T2DecayResult:
268
    """T2 decay measurement result."""
269
    
270
    def __init__(self, t2_time: 'cirq.Duration',
271
                 fit_quality: float) -> None:
272
        """Initialize T2 result."""
273
```
274

275
### Readout Error Characterization
276

277
```python { .api }
278
def estimate_single_qubit_readout_errors(sampler: 'cirq.Sampler',
279
                                       qubit: 'cirq.Qid') -> 'SingleQubitReadoutCalibrationResult':
280
    """Estimate single-qubit readout errors."""
281

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

286
class SingleQubitReadoutCalibrationResult:
287
    """Single-qubit readout calibration result."""
288
    
289
    def __init__(self, zero_state_errors: Tuple[float, float],
290
                 one_state_errors: Tuple[float, float]) -> None:
291
        """Initialize readout calibration result."""
292

293
class TensoredConfusionMatrices:
294
    """Tensor product of confusion matrices."""
295
    
296
    def __init__(self, confusion_matrices: Sequence[np.ndarray]) -> None:
297
        """Initialize tensored confusion matrices."""
298
```
299

300
## Interoperability
301

302
### Quirk Integration
303

304
```python { .api }
305
def quirk_json_to_circuit(json_text: str) -> 'cirq.Circuit':
306
    """Convert Quirk JSON to Cirq circuit.
307
    
308
    Args:
309
        json_text: Quirk circuit as JSON string
310
        
311
    Returns:
312
        Equivalent Cirq circuit
313
    """
314

315
def quirk_url_to_circuit(url: str) -> 'cirq.Circuit':
316
    """Convert Quirk URL to Cirq circuit.
317
    
318
    Args:
319
        url: Quirk circuit URL
320
        
321
    Returns:
322
        Equivalent Cirq circuit
323
    """
324
```
325

326
### Neutral Atoms Support
327

328
```python { .api }
329
def is_native_neutral_atom_gate(gate: 'cirq.Gate') -> bool:
330
    """Check if gate is native to neutral atom systems."""
331

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

336
## Usage Examples
337

338
### Duration and Timing
339

340
```python
341
import cirq
342

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

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

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

354
# Create timestamp
355
timestamp = cirq.Timestamp(nanos=100)
356
print(f"Timestamp: {timestamp}")
357
```
358

359
### Measurement Results Visualization
360

361
```python
362
import cirq
363
import matplotlib.pyplot as plt
364

365
# Create circuit and get results
366
qubits = cirq.LineQubit.range(2)
367
circuit = cirq.Circuit([
368
    cirq.H(qubits[0]),
369
    cirq.CNOT(qubits[0], qubits[1]),
370
    cirq.measure(*qubits, key='bell_pair')
371
])
372

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

376
# Plot histogram
377
fig, ax = plt.subplots()
378
cirq.plot_state_histogram(result, ax=ax)
379
ax.set_title('Bell State Measurement Results')
380
plt.show()
381

382
# Get histogram data
383
histogram = cirq.get_state_histogram(result)
384
print(f"Measurement histogram: {histogram}")
385
```
386

387
### Working with Product States
388

389
```python
390
import cirq
391

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

395
# Create circuit preparing |+0⟩ state
396
circuit = cirq.Circuit([
397
    cirq.H(qubits[0])  # |0⟩ → |+⟩
398
    # qubits[1] stays in |0⟩
399
])
400

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

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

411
### Simple Experiments
412

413
```python
414
import cirq
415
import numpy as np
416

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

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

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

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

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

442
### Interoperability Examples
443

444
```python
445
import cirq
446

447
# Convert from Quirk (example JSON)
448
quirk_json = '''
449
{
450
    "cols": [
451
        ["H"],
452
        ["•", "X"]
453
    ]
454
}
455
'''
456

457
try:
458
    # This would work with actual Quirk integration
459
    # quirk_circuit = cirq.quirk_json_to_circuit(quirk_json)
460
    # print("Converted Quirk circuit:")
461
    # print(quirk_circuit)
462
    print("Quirk integration available via quirk_json_to_circuit()")
463
except:
464
    print("Quirk integration requires proper JSON format")
465

466
# Check neutral atom compatibility
467
h_gate = cirq.H
468
x_gate = cirq.X
469

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

474
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.