cirq.sim.Simulator

A sparse matrix state vector simulator that uses numpy.

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

View aliases

Main aliases

cirq.Simulator, cirq.sim.sparse_simulator.Simulator

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
)

Used in the notebooks

Used in the tutorials
Introduction to Cirq Textbook algorithms in Cirq State Histograms Fermi-Hubbard experiment example Quantum chess

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.

Args
`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.

Raises
`ValueError`	If the given dtype is not complex.

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.

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

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.

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

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.

Args
`circuit`	The circuit to simulate.
`param_resolver`	Parameters to run with the program.
`seed`	Random state to use as a seed. This must be provided manually - if the simulator has its own seed, it will not be used unless it is passed as this argument.
`repetitions`	The number of repetitions to simulate.
`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.

cirq.sim.Simulator

View aliases

Used in the notebooks

Args

Raises

Methods

compute_amplitudes

compute_amplitudes_sweep

compute_amplitudes_sweep_iter

run

run_async

run_batch

run_sweep

run_sweep_async

run_sweep_iter

sample

Examples:

sample_expectation_values

sample_from_amplitudes

simulate

simulate_expectation_values

simulate_expectation_values_sweep

simulate_expectation_values_sweep_iter

simulate_moment_steps

simulate_sweep

simulate_sweep_iter

`compute_amplitudes`

`compute_amplitudes_sweep`

`compute_amplitudes_sweep_iter`

`run`

`run_async`

`run_batch`

`run_sweep`

`run_sweep_async`

`run_sweep_iter`

`sample`

`sample_expectation_values`

`sample_from_amplitudes`

`simulate`

`simulate_expectation_values`

`simulate_expectation_values_sweep`

`simulate_expectation_values_sweep_iter`

`simulate_moment_steps`

`simulate_sweep`

`simulate_sweep_iter`