cirq.sim.Simulator

A sparse matrix state vector simulator that uses numpy.

Inherits From: SimulatesIntermediateStateVector, SimulatorBase, SimulatesIntermediateState, SimulatesFinalState, SimulatesSamples, Sampler, SimulatesAmplitudes, SimulatesExpectationValues

cirq.sim.Simulator(
    *,
    dtype: Type[np.number] = np.complex64,
    noise: "cirq.NOISE_MODEL_LIKE" = None,
    seed: "cirq.RANDOM_STATE_OR_SEED_LIKE" = None,
    split_untangled_states: bool = True
)

This simulator can be applied on circuits that are made up of operations that have a _unitary_ method, or _has_unitary_ and _apply_unitary_, _mixture_ methods, are measurements, or support a _decompose_ method that returns operations satisfying these same conditions. That is to say, the operations should follow the cirq.SupportsConsistentApplyUnitary protocol, the cirq.SupportsUnitary protocol, the cirq.SupportsMixture protocol, or the cirq.CompositeOperation protocol. It is also permitted for the circuit to contain measurements which are operations that support cirq.SupportsKraus and cirq.SupportsMeasurementKey

This simulator supports four types of simulation.

Run simulations which mimic running on actual quantum hardware. These simulations do not give access to the state vector (like actual hardware). There are two variations of run methods, one which takes in a single (optional) way to resolve parameterized circuits, and a second which takes in a list or sweep of parameter resolver:

run(circuit, param_resolver, repetitions)

run_sweep(circuit, params, repetitions)

The simulation performs optimizations if the number of repetitions is greater than one and all measurements in the circuit are terminal (at the end of the circuit). These methods return Results which contain both the measurement results, but also the parameters used for the parameterized circuit operations. The initial state of a run is always the all 0s state in the computational basis.

By contrast the simulate methods of the simulator give access to the state vector of the simulation at the end of the simulation of the circuit. These methods take in two parameters that the run methods do not: a qubit order and an initial state. The qubit order is necessary because an ordering must be chosen for the kronecker product (see SparseSimulationTrialResult for details of this ordering). The initial state can be either the full state vector, or an integer which represents the initial state of being in a computational basis state for the binary representation of that integer. Similar to run methods, there are two simulate methods that run for single runs or for sweeps across different parameters:

simulate(circuit, param_resolver, qubit_order, initial_state)

simulate_sweep(circuit, params, qubit_order, initial_state)

The simulate methods in contrast to the run methods do not perform repetitions. The result of these simulations is a SparseSimulationTrialResult which contains, in addition to measurement results and information about the parameters that were used in the simulation,access to the state via the state method and StateVectorMixin methods.

If one wishes to perform simulations that have access to the state vector as one steps through running the circuit there is a generator which can be iterated over and each step is an object that gives access to the state vector. This stepping through a Circuit is done on a Moment by Moment manner.

simulate_moment_steps(circuit, param_resolver, qubit_order,
                      initial_state)

One can iterate over the moments via

for step_result in simulate_moments(circuit):
   # do something with the state vector via step_result.state_vector

Note also that simulations can be stochastic, i.e. return different results for different runs. The first version of this occurs for measurements, where the results of the measurement are recorded. This can also occur when the circuit has mixtures of unitaries.

If only the expectation values for some observables on the final state are required, there are methods for that as well. These methods take a mapping of names to observables, and return a map (or list of maps) of those names to the corresponding expectation values.

simulate_expectation_values(circuit, observables, param_resolver,
                            qubit_order, initial_state,
                            permit_terminal_measurements)

simulate_expectation_values_sweep(circuit, observables, params,
                                  qubit_order, initial_state,
                                  permit_terminal_measurements)

Expectation values generated by these methods are exact (up to precision of the floating-point type used); the closest analogy on hardware requires estimating the expectation values from several samples.

See Simulator for the definitions of the supported methods.

dtype The numpy.dtype used by the simulation. One of numpy.complex64 or numpy.complex128.
noise A noise model to apply while simulating.
seed The random seed to use for this simulator.
split_untangled_states If True, optimizes simulation by running unentangled qubit sets independently and merging those states at the end.

Methods

compute_amplitudes

View source

compute_amplitudes(
    program: "cirq.AbstractCircuit",
    bitstrings: Sequence[int],
    param_resolver: "study.ParamResolverOrSimilarType" = None,
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT
) -> Sequence[complex]

Computes the desired amplitudes.

The initial state is assumed to be the all zeros state.

Args
program The circuit to simulate.
bitstrings The bitstrings whose amplitudes are desired, input as an integer array where each integer is formed from measured qubit values according to qubit_order from most to least significant qubit, i.e. in big-endian ordering.
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.

Returns
List of amplitudes.

compute_amplitudes_sweep

View source

compute_amplitudes_sweep(
    program: "cirq.AbstractCircuit",
    bitstrings: Sequence[int],
    params: cirq.study.Sweepable,
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT
) -> Sequence[Sequence[complex]]

Wraps computed amplitudes in a list.

Prefer overriding compute_amplitudes_sweep_iter.

compute_amplitudes_sweep_iter

View source

compute_amplitudes_sweep_iter(
    program: "cirq.AbstractCircuit",
    bitstrings: Sequence[int],
    params: cirq.study.Sweepable,
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT
) -> Iterator[Sequence[complex]]

Computes the desired amplitudes.

The initial state is assumed to be the all zeros state.

Args
program The circuit to simulate.
bitstrings The bitstrings whose amplitudes are desired, input as an integer array where each integer is formed from measured qubit values according to qubit_order from most to least significant qubit, i.e. in big-endian ordering.
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.

Returns
An Iterator over lists of amplitudes. The outer dimension indexes the circuit parameters and the inner dimension indexes bitstrings.

run

View source

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

Samples from the given Circuit.

By default, the run_async method invokes this method on another thread. So this method is supposed to be thread safe.

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, *, repetitions
)

Asynchronously samples from the given Circuit.

By default, this method invokes run 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.
repetitions The number of times to sample.

Returns
An awaitable Result.

run_batch

View source

run_batch(
    programs: Sequence['cirq.AbstractCircuit'],
    params_list: Optional[List['cirq.Sweepable']] = None,
    repetitions: Union[int, List[int]] = 1
) -> List[List['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.

run_sweep

View source

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

Samples from the given Circuit.

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

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 sweeps and 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 One or more mappings from parameter keys to parameter values to use. For each parameter assignment, repetitions samples will be taken.
repetitions The number of times to sample.

Returns
An awaitable Result.

run_sweep_iter

View source

run_sweep_iter(
    program: "cirq.AbstractCircuit",
    params: cirq.study.Sweepable,
    repetitions: int = 1
) -> Iterator[cirq.study.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.

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.

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 = None,
    params: "cirq.Sweepable" = False,
    permit_terminal_measurements: bool = False
) -> List[List[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.

simulate

View source

simulate(
    program: "cirq.AbstractCircuit",
    param_resolver: "study.ParamResolverOrSimilarType" = None,
    qubit_order: cirq.ops.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_expectation_values

View source

simulate_expectation_values(
    program: "cirq.AbstractCircuit",
    observables: Union['cirq.PauliSumLike', List['cirq.PauliSumLike']],
    param_resolver: "study.ParamResolverOrSimilarType" = None,
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None,
    permit_terminal_measurements: bool = False
) -> List[float]

Simulates the supplied circuit and calculates exact expectation values for the given observables on its final state.

This method has no perfect analogy in hardware. Instead compare with Sampler.sample_expectation_values, which calculates estimated expectation values by sampling multiple times.

Args
program The circuit to simulate.
observables An observable or list of observables.
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.
permit_terminal_measurements If the provided circuit ends with measurement(s), 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 values, with the value at index n corresponding to observables[n] from the input.

Raises
ValueError if 'program' has terminal measurement(s) and 'permit_terminal_measurements' is False.

simulate_expectation_values_sweep

View source

simulate_expectation_values_sweep(
    program: "cirq.AbstractCircuit",
    observables: Union['cirq.PauliSumLike', List['cirq.PauliSumLike']],
    params: "study.Sweepable",
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None,
    permit_terminal_measurements: bool = False
) -> List[List[float]]

Wraps computed expectation values in a list.

Prefer overriding simulate_expectation_values_sweep_iter.

simulate_expectation_values_sweep_iter

View source

simulate_expectation_values_sweep_iter(
    program: "cirq.AbstractCircuit",
    observables: Union['cirq.PauliSumLike', List['cirq.PauliSumLike']],
    params: "cirq.Sweepable",
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None,
    permit_terminal_measurements: bool = False
) -> Iterator[List[float]]

Simulates the supplied circuit and calculates exact expectation values for the given observables on its final state, sweeping over the given params.

This method has no perfect analogy in hardware. Instead compare with Sampler.sample_expectation_values, which calculates estimated expectation values by sampling multiple times.

Args
program The circuit to simulate.
observables An observable or list of observables.
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. The form of this state depends on the simulation implementation. See documentation of the implementing class for details.
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
An Iterator over 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 'program' has terminal measurement(s) and 'permit_terminal_measurements' is False.

simulate_moment_steps

View source

simulate_moment_steps(
    circuit: cirq.circuits.AbstractCircuit,
    param_resolver: "study.ParamResolverOrSimilarType" = None,
    qubit_order: cirq.ops.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.study.Sweepable,
    qubit_order: cirq.ops.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.study.Sweepable,
    qubit_order: cirq.ops.QubitOrderOrList = cirq.ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> Iterator[cirq.sim.simulator.TSimulationTrialResult]

Simulates the supplied Circuit.

This method returns a result which allows access to the entire state vector. In contrast to simulate, this allows for sweeping over different parameter values.

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.