0
# Simulators and Simulation
1
2
The sim module provides classical simulation capabilities for quantum circuits, including multiple simulation backends optimized for different use cases and performance requirements. It supports state vector simulation, density matrix simulation, and specialized Clifford simulation.
3
4
## Core Simulator Classes
5
6
### Simulator - State Vector Simulator
7
8
The default sparse state vector simulator, efficient for pure state quantum circuits.
9
10
```python { .api }
11
class Simulator(SimulatorBase):
12
"""Sparse state vector simulator."""
13
14
def __init__(self, *, dtype: Type[np.number] = np.complex64,
15
noise: 'cirq.NoiseModel' = None,
16
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> None:
17
"""Initialize state vector simulator.
18
19
Args:
20
dtype: Numeric type for state vector (complex64 or complex128)
21
noise: Noise model to apply during simulation
22
seed: Random seed for sampling and noise
23
"""
24
25
def run(self, program: 'cirq.CIRCUIT_LIKE',
26
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
27
repetitions: int = 1) -> 'cirq.Result':
28
"""Run circuit and return measurement results.
29
30
Args:
31
program: Circuit to simulate
32
param_resolver: Parameters for the circuit
33
repetitions: Number of times to run the circuit
34
35
Returns:
36
Result containing measurement outcomes
37
"""
38
39
def run_sweep(self, program: 'cirq.CIRCUIT_LIKE',
40
params: 'cirq.Sweepable',
41
repetitions: int = 1) -> List['cirq.Result']:
42
"""Run circuit over parameter sweep."""
43
44
def simulate(self, program: 'cirq.CIRCUIT_LIKE',
45
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
46
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
47
initial_state: 'cirq.STATE_VECTOR_LIKE' = None) -> 'StateVectorTrialResult':
48
"""Simulate circuit and return final state.
49
50
Args:
51
program: Circuit to simulate
52
param_resolver: Parameter values
53
qubit_order: Ordering of qubits in state vector
54
initial_state: Initial state vector
55
56
Returns:
57
Trial result with final state vector
58
"""
59
60
def simulate_sweep(self, program: 'cirq.CIRCUIT_LIKE',
61
params: 'cirq.Sweepable',
62
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
63
initial_state: 'cirq.STATE_VECTOR_LIKE' = None) -> List['StateVectorTrialResult']:
64
"""Simulate circuit over parameter sweep."""
65
66
def simulate_moment_steps(self, circuit: 'cirq.Circuit',
67
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
68
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
69
initial_state: 'cirq.STATE_VECTOR_LIKE' = None) -> Iterator['StateVectorStepResult']:
70
"""Simulate circuit step by step, yielding after each moment."""
71
```
72
73
### DensityMatrixSimulator - Mixed State Simulator
74
75
Simulator using density matrix representation, supporting mixed states and decoherence.
76
77
```python { .api }
78
class DensityMatrixSimulator(SimulatorBase):
79
"""Density matrix simulator for mixed state simulation."""
80
81
def __init__(self, *, dtype: Type[np.number] = np.complex64,
82
noise: 'cirq.NoiseModel' = None,
83
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None,
84
ignore_measurement_results: bool = False) -> None:
85
"""Initialize density matrix simulator.
86
87
Args:
88
dtype: Numeric type for density matrix
89
noise: Noise model to apply
90
seed: Random seed
91
ignore_measurement_results: Whether to ignore measurement collapse
92
"""
93
94
def simulate(self, program: 'cirq.CIRCUIT_LIKE',
95
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
96
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
97
initial_state: 'cirq.QUANTUM_STATE_LIKE' = None) -> 'DensityMatrixTrialResult':
98
"""Simulate circuit and return final density matrix.
99
100
Args:
101
program: Circuit to simulate
102
param_resolver: Parameter values
103
qubit_order: Qubit ordering
104
initial_state: Initial state (pure or mixed)
105
106
Returns:
107
Trial result with final density matrix
108
"""
109
110
def simulate_moment_steps(self, circuit: 'cirq.Circuit',
111
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
112
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
113
initial_state: 'cirq.QUANTUM_STATE_LIKE' = None) -> Iterator['DensityMatrixStepResult']:
114
"""Simulate circuit step by step."""
115
```
116
117
### CliffordSimulator - Stabilizer State Simulator
118
119
Efficient simulator for Clifford circuits using stabilizer state representation.
120
121
```python { .api }
122
class CliffordSimulator(SimulatorBase):
123
"""Clifford circuit simulator using stabilizer states."""
124
125
def __init__(self, *, seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> None:
126
"""Initialize Clifford simulator."""
127
128
def run(self, program: 'cirq.CIRCUIT_LIKE',
129
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
130
repetitions: int = 1) -> 'cirq.Result':
131
"""Run Clifford circuit."""
132
133
def simulate(self, program: 'cirq.CIRCUIT_LIKE',
134
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
135
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
136
initial_state: Union['CliffordState', 'cirq.STATE_VECTOR_LIKE'] = None) -> 'CliffordTrialResult':
137
"""Simulate Clifford circuit and return stabilizer state.
138
139
Args:
140
program: Clifford circuit to simulate
141
param_resolver: Parameter values
142
qubit_order: Qubit ordering
143
initial_state: Initial stabilizer state
144
145
Returns:
146
Trial result with final Clifford state
147
"""
148
149
def simulate_moment_steps(self, circuit: 'cirq.Circuit',
150
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
151
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
152
initial_state: Union['CliffordState', 'cirq.STATE_VECTOR_LIKE'] = None) -> Iterator['CliffordSimulatorStepResult']:
153
"""Simulate Clifford circuit step by step."""
154
```
155
156
### ClassicalStateSimulator - Classical Bit Simulator
157
158
Efficient simulator for classical circuits and reversible classical computation.
159
160
```python { .api }
161
class ClassicalStateSimulator(SimulatorBase):
162
"""Classical state simulator for reversible classical computation."""
163
164
def __init__(self, *, seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> None:
165
"""Initialize classical simulator."""
166
167
def simulate(self, program: 'cirq.CIRCUIT_LIKE',
168
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
169
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
170
initial_state: Union[int, 'cirq.ProductState'] = 0) -> 'SimulationTrialResult':
171
"""Simulate classical circuit."""
172
```
173
174
### StabilizerSampler - Stabilizer State Sampling
175
176
Sampler for stabilizer states using efficient Clifford simulation.
177
178
```python { .api }
179
class StabilizerSampler:
180
"""Sampler for stabilizer states."""
181
182
def __init__(self, *, seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> None:
183
"""Initialize stabilizer sampler."""
184
185
def run(self, program: 'cirq.CIRCUIT_LIKE',
186
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
187
repetitions: int = 1) -> 'cirq.Result':
188
"""Sample from stabilizer circuit."""
189
```
190
191
## Simulator Base Classes and Interfaces
192
193
### SimulatorBase
194
195
Abstract base class for all simulators.
196
197
```python { .api }
198
class SimulatorBase:
199
"""Abstract base class for simulators."""
200
201
def __init__(self, *, dtype: Optional[Type[np.number]] = None,
202
noise: 'cirq.NoiseModel' = None,
203
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> None:
204
"""Initialize simulator base."""
205
206
def run(self, program: 'cirq.CIRCUIT_LIKE',
207
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
208
repetitions: int = 1) -> 'cirq.Result':
209
"""Run circuit and return measurement results."""
210
211
def run_sweep(self, program: 'cirq.CIRCUIT_LIKE',
212
params: 'cirq.Sweepable',
213
repetitions: int = 1) -> List['cirq.Result']:
214
"""Run circuit over parameter sweep."""
215
216
def sample(self, program: 'cirq.CIRCUIT_LIKE',
217
repetitions: int = 1,
218
params: 'cirq.Sweepable' = None) -> pd.DataFrame:
219
"""Sample measurement outcomes."""
220
```
221
222
### Simulation Interfaces
223
224
Interfaces that simulators can implement for different capabilities.
225
226
```python { .api }
227
class SimulatesAmplitudes:
228
"""Interface for simulators that can compute amplitudes."""
229
230
def compute_amplitudes(self, program: 'cirq.CIRCUIT_LIKE',
231
bitstrings: Sequence[int],
232
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
233
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT') -> Sequence[complex]:
234
"""Compute amplitudes for given bitstrings."""
235
236
class SimulatesExpectationValues:
237
"""Interface for simulators that can compute expectation values."""
238
239
def simulate_expectation_values(self, program: 'cirq.CIRCUIT_LIKE',
240
observables: Union['cirq.PauliSumLike', List['cirq.PauliSumLike']],
241
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
242
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
243
initial_state: 'cirq.STATE_VECTOR_LIKE' = None,
244
permit_terminal_measurements: bool = False) -> List[float]:
245
"""Simulate expectation values of observables."""
246
247
class SimulatesFinalState:
248
"""Interface for simulators that can return final states."""
249
250
def simulate(self, program: 'cirq.CIRCUIT_LIKE',
251
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
252
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
253
initial_state: Any = None) -> 'SimulationTrialResult':
254
"""Simulate circuit and return final state."""
255
256
class SimulatesIntermediateState:
257
"""Interface for simulators that can return intermediate states."""
258
259
def simulate_moment_steps(self, circuit: 'cirq.Circuit',
260
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
261
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
262
initial_state: Any = None) -> Iterator['StepResult']:
263
"""Simulate circuit step by step."""
264
265
class SimulatesIntermediateStateVector:
266
"""Interface for simulators that can return intermediate state vectors."""
267
268
class SimulatesSamples:
269
"""Interface for simulators that can generate samples."""
270
271
def run(self, program: 'cirq.CIRCUIT_LIKE',
272
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
273
repetitions: int = 1) -> 'cirq.Result':
274
"""Run circuit and return samples."""
275
```
276
277
## Simulation States
278
279
### SimulationState - Base State Class
280
281
```python { .api }
282
class SimulationState:
283
"""Base class for simulation states."""
284
285
def __init__(self, qubits: Sequence['cirq.Qid'],
286
log_of_measurement_results: Dict[str, Any] = None) -> None:
287
"""Initialize simulation state.
288
289
Args:
290
qubits: Qubits being simulated
291
log_of_measurement_results: Measurement results log
292
"""
293
294
@property
295
def qubits(self) -> Tuple['cirq.Qid', ...]:
296
"""Qubits in the simulation."""
297
298
@property
299
def log_of_measurement_results(self) -> Dict[str, Any]:
300
"""Log of measurement results."""
301
302
def copy(self, deep_copy_buffers: bool = True) -> 'SimulationState':
303
"""Create a copy of the simulation state."""
304
305
class SimulationStateBase(SimulationState):
306
"""Enhanced base class for simulation states."""
307
308
def kronecker_product(self, other: 'SimulationStateBase') -> 'SimulationStateBase':
309
"""Compute tensor product with another state."""
310
311
def factor(self, qubits: Sequence['cirq.Qid'], *, validate: bool = True,
312
atol: float = 1e-07) -> Tuple['SimulationStateBase', 'SimulationStateBase']:
313
"""Factor state into two subsystems."""
314
315
def transpose_to_qubit_order(self, qubits: Sequence['cirq.Qid']) -> 'SimulationStateBase':
316
"""Transpose state to different qubit ordering."""
317
```
318
319
### StateVectorSimulationState - Pure State Vector
320
321
```python { .api }
322
class StateVectorSimulationState(SimulationStateBase):
323
"""Simulation state using state vector representation."""
324
325
def __init__(self, qubits: Sequence['cirq.Qid'],
326
initial_state: 'cirq.STATE_VECTOR_LIKE' = 0,
327
dtype: Type[np.number] = np.complex64,
328
log_of_measurement_results: Dict[str, Any] = None) -> None:
329
"""Initialize state vector simulation state."""
330
331
@property
332
def target_tensor(self) -> np.ndarray:
333
"""State vector tensor."""
334
335
@property
336
def available_buffer(self) -> np.ndarray:
337
"""Available buffer for computations."""
338
339
def bloch_vector_of(self, qubit: 'cirq.Qid') -> np.ndarray:
340
"""Get Bloch vector representation of a qubit."""
341
342
def density_matrix_of(self, qubits: Sequence['cirq.Qid'] = None) -> np.ndarray:
343
"""Get density matrix of specified qubits."""
344
345
def dirac_notation(self, decimals: int = 2) -> str:
346
"""Get Dirac notation representation."""
347
```
348
349
### DensityMatrixSimulationState - Mixed State
350
351
```python { .api }
352
class DensityMatrixSimulationState(SimulationStateBase):
353
"""Simulation state using density matrix representation."""
354
355
def __init__(self, qubits: Sequence['cirq.Qid'],
356
initial_state: 'cirq.QUANTUM_STATE_LIKE' = 0,
357
dtype: Type[np.number] = np.complex64,
358
log_of_measurement_results: Dict[str, Any] = None) -> None:
359
"""Initialize density matrix simulation state."""
360
361
@property
362
def target_tensor(self) -> np.ndarray:
363
"""Density matrix tensor."""
364
365
def density_matrix_of(self, qubits: Sequence['cirq.Qid'] = None) -> np.ndarray:
366
"""Get density matrix of specified qubits."""
367
368
def bloch_vector_of(self, qubit: 'cirq.Qid') -> np.ndarray:
369
"""Get Bloch vector of a single qubit."""
370
```
371
372
### Clifford and Stabilizer States
373
374
```python { .api }
375
class CliffordTableauSimulationState(SimulationStateBase):
376
"""Simulation state using Clifford tableau representation."""
377
378
def __init__(self, tableau: 'cirq.CliffordTableau',
379
qubits: Sequence['cirq.Qid'],
380
log_of_measurement_results: Dict[str, Any] = None) -> None:
381
"""Initialize Clifford tableau state."""
382
383
class StabilizerSimulationState(SimulationStateBase):
384
"""General stabilizer simulation state."""
385
386
class StabilizerChFormSimulationState(SimulationStateBase):
387
"""Stabilizer state in CH-form representation."""
388
389
class StabilizerStateChForm:
390
"""CH-form stabilizer state representation."""
391
392
def __init__(self, num_qubits: int, initial_state: int = 0) -> None:
393
"""Initialize CH-form stabilizer state."""
394
395
def copy(self) -> 'StabilizerStateChForm':
396
"""Create a copy of the state."""
397
398
def inner_product_of_state_and_x(self, x: int) -> complex:
399
"""Compute <ψ|x> where |x> is computational basis state."""
400
401
def to_numpy(self) -> np.ndarray:
402
"""Convert to numpy state vector (exponential cost)."""
403
```
404
405
### Product States
406
407
```python { .api }
408
class SimulationProductState(SimulationStateBase):
409
"""Product state simulation (for classical-like states)."""
410
411
def __init__(self, qubits: Sequence['cirq.Qid'],
412
initial_state: Union[int, Dict['cirq.Qid', int], 'cirq.ProductState'] = 0,
413
log_of_measurement_results: Dict[str, Any] = None) -> None:
414
"""Initialize product state."""
415
416
@property
417
def state(self) -> Dict['cirq.Qid', int]:
418
"""Current computational basis state."""
419
```
420
421
### State Vector Mixin
422
423
```python { .api }
424
class StateVectorMixin:
425
"""Mixin providing state vector functionality."""
426
427
def state_vector(self) -> np.ndarray:
428
"""Get the full state vector."""
429
430
def dirac_notation(self, decimals: int = 2) -> str:
431
"""Get Dirac notation string."""
432
433
def bloch_vector_of(self, qubit: 'cirq.Qid') -> np.ndarray:
434
"""Get Bloch vector of single qubit."""
435
```
436
437
## Simulation Results
438
439
### Trial Results - Final State Results
440
441
```python { .api }
442
class SimulationTrialResult:
443
"""Result of a single simulation trial."""
444
445
def __init__(self, params: 'cirq.ParamResolver',
446
measurements: Dict[str, np.ndarray],
447
final_simulator_state: 'SimulationState') -> None:
448
"""Initialize trial result."""
449
450
@property
451
def params(self) -> 'cirq.ParamResolver':
452
"""Parameters used in this trial."""
453
454
@property
455
def measurements(self) -> Dict[str, np.ndarray]:
456
"""Measurement results keyed by measurement key."""
457
458
@property
459
def final_simulator_state(self) -> 'SimulationState':
460
"""Final simulation state after circuit execution."""
461
462
def histogram(self, *, key: str, fold_func: Callable = None) -> Dict[Any, int]:
463
"""Get histogram of measurement results."""
464
465
class SimulationTrialResultBase(SimulationTrialResult):
466
"""Base class for trial results with additional methods."""
467
468
def qubit_map(self) -> Dict['cirq.Qid', int]:
469
"""Map from qubits to their index in the state."""
470
471
def density_matrix_of(self, qubits: Sequence['cirq.Qid'] = None) -> np.ndarray:
472
"""Get density matrix of specified qubits."""
473
```
474
475
### Specific Trial Result Types
476
477
```python { .api }
478
class StateVectorTrialResult(SimulationTrialResultBase, StateVectorMixin):
479
"""Trial result for state vector simulation."""
480
481
@property
482
def final_state_vector(self) -> np.ndarray:
483
"""Final state vector."""
484
485
class DensityMatrixTrialResult(SimulationTrialResultBase):
486
"""Trial result for density matrix simulation."""
487
488
@property
489
def final_density_matrix(self) -> np.ndarray:
490
"""Final density matrix."""
491
492
class CliffordTrialResult(SimulationTrialResultBase):
493
"""Trial result for Clifford simulation."""
494
495
@property
496
def final_state(self) -> 'CliffordState':
497
"""Final Clifford state."""
498
499
class CliffordState:
500
"""Clifford stabilizer state."""
501
502
def __init__(self, tableau: 'cirq.CliffordTableau',
503
qubits: Sequence['cirq.Qid'] = None) -> None:
504
"""Initialize Clifford state."""
505
506
def stabilizers(self) -> List['cirq.PauliString']:
507
"""Get stabilizer generators."""
508
509
def destabilizers(self) -> List['cirq.PauliString']:
510
"""Get destabilizer generators."""
511
512
def to_numpy(self) -> np.ndarray:
513
"""Convert to state vector (exponential cost)."""
514
```
515
516
### Step Results - Intermediate States
517
518
```python { .api }
519
class StepResult:
520
"""Result after simulating one moment."""
521
522
def __init__(self, simulator_state: 'SimulationState') -> None:
523
"""Initialize step result."""
524
525
@property
526
def simulator_state(self) -> 'SimulationState':
527
"""Simulation state after this step."""
528
529
class StepResultBase(StepResult):
530
"""Enhanced step result with additional methods."""
531
532
def density_matrix_of(self, qubits: Sequence['cirq.Qid'] = None) -> np.ndarray:
533
"""Get density matrix of qubits."""
534
535
def qubit_map(self) -> Dict['cirq.Qid', int]:
536
"""Get qubit index mapping."""
537
538
class StateVectorStepResult(StepResultBase, StateVectorMixin):
539
"""Step result for state vector simulation."""
540
541
@property
542
def state_vector(self) -> np.ndarray:
543
"""Current state vector."""
544
545
class DensityMatrixStepResult(StepResultBase):
546
"""Step result for density matrix simulation."""
547
548
@property
549
def density_matrix(self) -> np.ndarray:
550
"""Current density matrix."""
551
552
class CliffordSimulatorStepResult(StepResultBase):
553
"""Step result for Clifford simulation."""
554
555
class SparseSimulatorStep(StateVectorStepResult):
556
"""Step result for sparse state vector simulator."""
557
```
558
559
## High-Level Simulation Functions
560
561
Convenient functions for common simulation tasks.
562
563
```python { .api }
564
def sample(program: 'cirq.CIRCUIT_LIKE', *, repetitions: int = 1,
565
noise: 'cirq.NoiseModel' = None,
566
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
567
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> 'cirq.Result':
568
"""Sample measurement outcomes from a circuit.
569
570
Args:
571
program: Circuit to sample from
572
repetitions: Number of samples to collect
573
noise: Noise model to apply
574
param_resolver: Parameter values
575
seed: Random seed
576
577
Returns:
578
Result containing measurement samples
579
"""
580
581
def sample_sweep(program: 'cirq.CIRCUIT_LIKE', params: 'cirq.Sweepable', *,
582
repetitions: int = 1,
583
noise: 'cirq.NoiseModel' = None,
584
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> List['cirq.Result']:
585
"""Sample over parameter sweep."""
586
587
def final_state_vector(program: 'cirq.CIRCUIT_LIKE', *,
588
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
589
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
590
initial_state: 'cirq.STATE_VECTOR_LIKE' = None,
591
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> np.ndarray:
592
"""Get final state vector after circuit execution.
593
594
Args:
595
program: Circuit to simulate
596
param_resolver: Parameter values
597
qubit_order: Qubit ordering for state vector
598
initial_state: Initial state vector
599
seed: Random seed
600
601
Returns:
602
Final state vector as numpy array
603
"""
604
605
def final_density_matrix(program: 'cirq.CIRCUIT_LIKE', *,
606
param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
607
qubit_order: 'cirq.QubitOrderOrList' = 'cirq.QubitOrder.DEFAULT',
608
initial_state: 'cirq.QUANTUM_STATE_LIKE' = None,
609
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> np.ndarray:
610
"""Get final density matrix after circuit execution."""
611
```
612
613
### Direct State Measurement Functions
614
615
```python { .api }
616
def measure_state_vector(state_vector: np.ndarray, indices: List[int], *,
617
qid_shape: Tuple[int, ...] = None,
618
out: np.ndarray = None,
619
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> Tuple[List[int], np.ndarray]:
620
"""Measure state vector and return outcomes and post-measurement state.
621
622
Args:
623
state_vector: State vector to measure
624
indices: Indices of qubits to measure
625
qid_shape: Shape of qid system
626
out: Output buffer for result state
627
seed: Random seed
628
629
Returns:
630
Tuple of (measurement_outcomes, post_measurement_state)
631
"""
632
633
def sample_state_vector(state_vector: np.ndarray, indices: List[int], *,
634
qid_shape: Tuple[int, ...] = None,
635
repetitions: int = 1,
636
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> np.ndarray:
637
"""Sample measurements from state vector without collapse."""
638
639
def measure_density_matrix(density_matrix: np.ndarray, indices: List[int], *,
640
qid_shape: Tuple[int, ...] = None,
641
out: np.ndarray = None,
642
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> Tuple[List[int], np.ndarray]:
643
"""Measure density matrix and return outcomes and post-measurement state."""
644
645
def sample_density_matrix(density_matrix: np.ndarray, indices: List[int], *,
646
qid_shape: Tuple[int, ...] = None,
647
repetitions: int = 1,
648
seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None) -> np.ndarray:
649
"""Sample measurements from density matrix without collapse."""
650
```
651
652
## Type Aliases
653
654
```python { .api }
655
CIRCUIT_LIKE = Union['cirq.AbstractCircuit', 'cirq.FrozenCircuit', Iterable[Any]]
656
"""Type alias for circuit-like objects."""
657
```
658
659
## Usage Examples
660
661
### Basic Circuit Simulation
662
663
```python
664
import cirq
665
import numpy as np
666
667
# Create a simple quantum circuit
668
qubits = cirq.LineQubit.range(2)
669
circuit = cirq.Circuit([
670
cirq.H(qubits[0]),
671
cirq.CNOT(qubits[0], qubits[1]),
672
cirq.measure(*qubits, key='result')
673
])
674
675
# Simulate with different backends
676
print("=== State Vector Simulation ===")
677
simulator = cirq.Simulator()
678
result = simulator.run(circuit, repetitions=100)
679
print(f"Measurement histogram: {result.histogram(key='result')}")
680
681
# Get final state without measurement
682
circuit_no_measure = circuit[:-1]
683
final_state = simulator.simulate(circuit_no_measure)
684
print(f"Final state vector shape: {final_state.final_state_vector.shape}")
685
print(f"Final state (Dirac notation): {final_state.dirac_notation()}")
686
687
print("\n=== Density Matrix Simulation ===")
688
dm_simulator = cirq.DensityMatrixSimulator()
689
dm_result = dm_simulator.simulate(circuit_no_measure)
690
print(f"Final density matrix shape: {dm_result.final_density_matrix.shape}")
691
```
692
693
### Noisy Simulation
694
695
```python
696
import cirq
697
698
# Create circuit with noise
699
qubits = cirq.LineQubit.range(2)
700
circuit = cirq.Circuit([
701
cirq.H(qubits[0]),
702
cirq.CNOT(qubits[0], qubits[1])
703
])
704
705
# Define noise model
706
noise_model = cirq.ConstantQubitNoiseModel(cirq.depolarize(p=0.01))
707
708
# Simulate with noise using density matrix
709
dm_simulator = cirq.DensityMatrixSimulator(noise=noise_model)
710
noisy_result = dm_simulator.simulate(circuit)
711
712
print("Clean vs Noisy Simulation:")
713
clean_result = cirq.DensityMatrixSimulator().simulate(circuit)
714
print(f"Clean final state purity: {np.trace(clean_result.final_density_matrix @ clean_result.final_density_matrix).real:.4f}")
715
print(f"Noisy final state purity: {np.trace(noisy_result.final_density_matrix @ noisy_result.final_density_matrix).real:.4f}")
716
```
717
718
### Step-by-Step Simulation
719
720
```python
721
import cirq
722
723
# Create multi-moment circuit
724
qubits = cirq.LineQubit.range(2)
725
circuit = cirq.Circuit([
726
cirq.H(qubits[0]),
727
cirq.Moment([cirq.X(qubits[1])]),
728
cirq.CNOT(qubits[0], qubits[1]),
729
cirq.Moment([cirq.Z(qubits[0]), cirq.Y(qubits[1])])
730
])
731
732
# Simulate step by step
733
simulator = cirq.Simulator()
734
print("Step-by-step simulation:")
735
for i, step_result in enumerate(simulator.simulate_moment_steps(circuit)):
736
print(f"After moment {i}: {step_result.dirac_notation()}")
737
```
738
739
### Clifford Circuit Simulation
740
741
```python
742
import cirq
743
744
# Create Clifford circuit (only Clifford gates)
745
qubits = cirq.LineQubit.range(3)
746
clifford_circuit = cirq.Circuit([
747
cirq.H(qubits[0]),
748
cirq.CNOT(qubits[0], qubits[1]),
749
cirq.S(qubits[2]),
750
cirq.CZ(qubits[1], qubits[2]),
751
cirq.measure(*qubits, key='result')
752
])
753
754
# Use Clifford simulator for efficiency
755
clifford_sim = cirq.CliffordSimulator()
756
result = clifford_sim.run(clifford_circuit, repetitions=1000)
757
print(f"Clifford simulation results: {result.histogram(key='result')}")
758
759
# Get stabilizer representation
760
final_state = clifford_sim.simulate(clifford_circuit[:-1]) # Without measurement
761
print(f"Final Clifford state stabilizers: {final_state.final_state.stabilizers()[:3]}")
762
```
763
764
### High-Level Convenience Functions
765
766
```python
767
import cirq
768
import numpy as np
769
770
# Using convenience functions
771
qubits = cirq.LineQubit.range(2)
772
circuit = cirq.Circuit([
773
cirq.H(qubits[0]),
774
cirq.CNOT(qubits[0], qubits[1])
775
])
776
777
# Get final state vector directly
778
final_state = cirq.final_state_vector(circuit)
779
print(f"Final state: {final_state}")
780
781
# Sample directly from circuit
782
samples = cirq.sample(circuit + cirq.measure(*qubits, key='result'), repetitions=100)
783
print(f"Direct sampling: {samples.histogram(key='result')}")
784
785
# Parameterized simulation
786
import sympy
787
theta = sympy.Symbol('theta')
788
param_circuit = cirq.Circuit([
789
cirq.rx(theta)(qubits[0]),
790
cirq.CNOT(qubits[0], qubits[1])
791
])
792
793
# Sweep over parameter values
794
param_sweep = cirq.Linspace('theta', 0, np.pi, 5)
795
results = cirq.sample_sweep(param_circuit + cirq.measure(*qubits, key='result'),
796
param_sweep, repetitions=100)
797
for i, result in enumerate(results):
798
theta_val = param_sweep[i].param_dict['theta']
799
print(f"θ = {theta_val:.3f}: {result.histogram(key='result')}")
800
```
801
802
This comprehensive simulation framework provides the foundation for classical quantum circuit simulation with multiple backends optimized for different use cases and performance requirements.