cirq.sim.CliffordSimulator

See Stable See Nightly

View source on GitHub

An efficient simulator for Clifford circuits.

Inherits From: SimulatorBase, SimulatesIntermediateState, SimulatesFinalState, SimulatesSamples, Sampler

View aliases

Main aliases

cirq.CliffordSimulator, cirq.sim.clifford.CliffordSimulator, cirq.sim.clifford.clifford_simulator.CliffordSimulator

cirq.sim.CliffordSimulator(
    seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE' = None,
    split_untangled_states: bool = False
)

Used in the notebooks

Used in the tutorials
Hidden linear function problem

Args
seed	The random seed to use for this simulator.
split_untangled_states	Optimizes simulation by running separable states independently and merging those states at the end.

Methods

is_supported_operation

View source

@staticmethod
is_supported_operation(
    op: 'cirq.Operation'
) -> bool

Checks whether given operation can be simulated by this simulator.

run

View source

run(
    program: 'cirq.AbstractCircuit',
    param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
    repetitions: int = 1
) -> 'cirq.Result'

Samples from the given Circuit.

Args
program	The circuit to sample from.
param_resolver	Parameters to run with the program.
repetitions	The number of times to sample.

Returns
Result for a run.

run_async

View source

run_async(
    program, param_resolver=None, repetitions=1
)

Asynchronously samples from the given Circuit.

Args
program	The circuit to sample from.
param_resolver	Parameters to run with the program.
repetitions	The number of times to sample.

Returns
Result for a run.

run_batch

View source

run_batch(
    programs: Sequence['cirq.AbstractCircuit'],
    params_list: Optional[List['cirq.Sweepable']] = None,
    repetitions: Union[int, List[int]] = 1
) -> Sequence[Sequence['cirq.Result']]

Runs the supplied circuits.

Each circuit provided in programs will pair with the optional associated parameter sweep provided in the params_list, and be run with the associated repetitions provided in repetitions (if repetitions is an integer, then all runs will have that number of repetitions). If params_list is specified, then the number of circuits is required to match the number of sweeps. Similarly, when repetitions is a list, the number of circuits is required to match the length of this list.

By default, this method simply invokes run_sweep sequentially for each (circuit, parameter sweep, repetitions) tuple. Child classes that are capable of sampling batches more efficiently should override it to use other strategies. Note that child classes may have certain requirements that must be met in order for a speedup to be possible, such as a constant number of repetitions being used for all circuits. Refer to the documentation of the child class for any such requirements.

Args
programs	The circuits to execute as a batch.
params_list	Parameter sweeps to use with the circuits. The number of sweeps should match the number of circuits and will be paired in order with the circuits.
repetitions	Number of circuit repetitions to run. Can be specified as a single value to use for all runs, or as a list of values, one for each circuit.

Returns
A list of lists of TrialResults. The outer list corresponds to the circuits, while each inner list contains the TrialResults for the corresponding circuit, in the order imposed by the associated parameter sweep.

Raises
ValueError	If length of programs is not equal to the length of params_list or the length of repetitions.

run_sweep

View source

run_sweep(
    program: 'cirq.AbstractCircuit',
    params: 'cirq.Sweepable',
    repetitions: int = 1
) -> Sequence['cirq.Result']

Samples from the given Circuit.

This allows for sweeping over different parameter values, unlike the run method.

Args
program	The circuit to sample from.
params	Parameters to run with the program.
repetitions	The number of times to sample.

Returns
Result list for this run; one for each possible parameter resolver.

run_sweep_async

View source

run_sweep_async(
    program, params, repetitions=1
)

Asynchronously samples from the given Circuit.

By default, this method invokes run_sweep synchronously and simply exposes its result is an awaitable. Child classes that are capable of true asynchronous sampling should override it to use other strategies.

Args
program	The circuit to sample from.
params	Parameters to run with the program.
repetitions	The number of times to sample.

Returns
Result list for this run; one for each possible parameter resolver.

run_sweep_iter

View source

run_sweep_iter(
    program: 'cirq.AbstractCircuit',
    params: 'cirq.Sweepable',
    repetitions: int = 1
) -> Iterator['cirq.Result']

Runs the supplied Circuit, mimicking quantum hardware.

In contrast to run, this allows for sweeping over different parameter values.

Args
program	The circuit to simulate.
params	Parameters to run with the program.
repetitions	The number of repetitions to simulate.

Returns
Result list for this run; one for each possible parameter resolver.

Raises
ValueError	If the circuit has no measurements.

sample

View source

sample(
    program: 'cirq.AbstractCircuit',
    *,
    repetitions: int = 1,
    params: 'cirq.Sweepable' = None
) -> 'pd.DataFrame'

Samples the given Circuit, producing a pandas data frame.

Args
program	The circuit to sample from.
repetitions	The number of times to sample the program, for each parameter mapping.
params	Maps symbols to one or more values. This argument can be a dictionary, a list of dictionaries, a cirq.Sweep, a list of cirq.Sweep, etc. The program will be sampled repetition times for each mapping. Defaults to a single empty mapping.

Returns

A pandas.DataFrame with a row for each sample, and a column for each measurement key as well as a column for each symbolic parameter. Measurement results are stored as a big endian integer representation with one bit for each measured qubit in the key. See cirq.big_endian_int_to_bits and similar functions for how to convert this integer into bits. There is an also index column containing the repetition number, for each parameter assignment.

Raises
ValueError	If a supplied sweep is invalid.

Examples:

a, b, c = cirq.LineQubit.range(3)
sampler = cirq.Simulator()
circuit = cirq.Circuit(cirq.X(a),
                       cirq.measure(a, key='out'))
print(sampler.sample(circuit, repetitions=4))
   out
0    1
1    1
2    1
3    1

circuit = cirq.Circuit(cirq.X(a),
                       cirq.CNOT(a, b),
                       cirq.measure(a, b, c, key='out'))
print(sampler.sample(circuit, repetitions=4))
   out
0    6
1    6
2    6
3    6

circuit = cirq.Circuit(cirq.X(a)**sympy.Symbol('t'),
                       cirq.measure(a, key='out'))
print(sampler.sample(
    circuit,
    repetitions=3,
    params=[{'t': 0}, {'t': 1}]))
   t  out
0  0    0
1  0    0
2  0    0
0  1    1
1  1    1
2  1    1

sample_expectation_values

View source

sample_expectation_values(
    program: 'cirq.AbstractCircuit',
    observables: Union['cirq.PauliSumLike', List['cirq.PauliSumLike']],
    *,
    num_samples: int,
    params: 'cirq.Sweepable' = None,
    permit_terminal_measurements: bool = False
) -> Sequence[Sequence[float]]

Calculates estimated expectation values from samples of a circuit.

Please see also cirq.work.measure_observables for more control over how to measure a suite of observables.

This method can be run on any device or simulator that supports circuit sampling. Compare with simulate_expectation_values in simulator.py, which is limited to simulators but provides exact results.

Args
program	The circuit which prepares a state from which we sample expectation values.
observables	A list of observables for which to calculate expectation values.
num_samples	The number of samples to take. Increasing this value increases the statistical accuracy of the estimate.
params	Parameters to run with the program.
permit_terminal_measurements	If the provided circuit ends in a measurement, this method will generate an error unless this is set to True. This is meant to prevent measurements from ruining expectation value calculations.

Returns
A list of expectation-value lists. The outer index determines the sweep, and the inner index determines the observable. For instance, results[1][3] would select the fourth observable measured in the second sweep.

Raises
ValueError	If the number of samples was not positive, if empty observables were supplied, or if the provided circuit has terminal measurements and permit_terminal_measurements is true.

simulate

View source

simulate(
    program: 'cirq.AbstractCircuit',
    param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
    qubit_order: 'cirq.QubitOrderOrList' = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> cirq.sim.simulator.TSimulationTrialResult

Simulates the supplied Circuit.

This method returns a result which allows access to the entire simulator's final state.

Args
program	The circuit to simulate.
param_resolver	Parameters to run with the program.
qubit_order	Determines the canonical ordering of the qubits. This is often used in specifying the initial state, i.e. the ordering of the computational basis states.
initial_state	The initial state for the simulation. The form of this state depends on the simulation implementation. See documentation of the implementing class for details.

Returns
SimulationTrialResults for the simulation. Includes the final state.

simulate_moment_steps

View source

simulate_moment_steps(
    circuit: 'cirq.AbstractCircuit',
    param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
    qubit_order: 'cirq.QubitOrderOrList' = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> Iterator[cirq.sim.simulator.TStepResult]

Returns an iterator of StepResults for each moment simulated.

If the circuit being simulated is empty, a single step result should be returned with the state being set to the initial state.

Args
circuit	The Circuit to simulate.
param_resolver	A ParamResolver for determining values of Symbols.
qubit_order	Determines the canonical ordering of the qubits. This is often used in specifying the initial state, i.e. the ordering of the computational basis states.
initial_state	The initial state for the simulation. This can be either a raw state or a TActOnArgs. The form of the raw state depends on the simulation implementation. See documentation of the implementing class for details.

Returns
Iterator that steps through the simulation, simulating each moment and returning a StepResult for each moment.

simulate_sweep

View source

simulate_sweep(
    program: 'cirq.AbstractCircuit',
    params: 'cirq.Sweepable',
    qubit_order: 'cirq.QubitOrderOrList' = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> List[cirq.sim.simulator.TSimulationTrialResult]

Wraps computed states in a list.

Prefer overriding simulate_sweep_iter.

simulate_sweep_iter

View source

simulate_sweep_iter(
    program: 'cirq.AbstractCircuit',
    params: 'cirq.Sweepable',
    qubit_order: 'cirq.QubitOrderOrList' = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> Iterator[cirq.sim.simulator.TSimulationTrialResult]

Simulates the supplied Circuit.

This particular implementation overrides the base implementation such that an unparameterized prefix circuit is simulated and fed into the parameterized suffix circuit.

Args
program	The circuit to simulate.
params	Parameters to run with the program.
qubit_order	Determines the canonical ordering of the qubits. This is often used in specifying the initial state, i.e. the ordering of the computational basis states.
initial_state	The initial state for the simulation. This can be either a raw state or an OperationTarget. The form of the raw state depends on the simulation implementation. See documentation of the implementing class for details.

Returns
List of SimulationTrialResults for this run, one for each possible parameter resolver.