![]() |
A sparse matrix state vector simulator that uses numpy.
Inherits From: SimulatesSamples
, Sampler
, SimulatesIntermediateStateVector
, SimulatesAmplitudes
, SimulatesIntermediateState
, SimulatesFinalState
cirq.sim.Simulator(
*,
dtype: Type[np.number] = np.complex64,
seed: "cirq.RANDOM_STATE_OR_SEED_LIKE" = None
)
Used in the notebooks
Used in the tutorials |
---|
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.SupportsChannel
and cirq.SupportsMeasurementKey
This simulator supports three 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 Result
s 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.
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 .
|
seed
|
The random seed to use for this simulator. |
Methods
compute_amplitudes
compute_amplitudes(
program: "cirq.Circuit",
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
compute_amplitudes_sweep(
program: "cirq.Circuit",
bitstrings: Sequence[int],
params: cirq.study.Sweepable
,
qubit_order: cirq.ops.QubitOrderOrList
= cirq.ops.QubitOrder.DEFAULT
) -> Sequence[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 | |
---|---|
List of lists of amplitudes. The outer dimension indexes the circuit parameters and the inner dimension indexes the bitstrings. |
run
run(
program: "cirq.Circuit",
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
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
run_batch(
programs: List['cirq.Circuit'],
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
run_sweep(
program: "cirq.Circuit",
params: cirq.study.Sweepable
,
repetitions: int = 1
) -> List[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. |
run_sweep_async
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. |
sample
sample(
program: "cirq.Circuit",
*,
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
simulate
simulate(
program: "cirq.Circuit",
param_resolver: "study.ParamResolverOrSimilarType" = None,
qubit_order: cirq.ops.QubitOrderOrList
= cirq.ops.QubitOrder.DEFAULT,
initial_state: Any = None
) -> "SimulationTrialResult"
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
simulate_moment_steps(
circuit: cirq.circuits.Circuit
,
param_resolver: "study.ParamResolverOrSimilarType" = None,
qubit_order: cirq.ops.QubitOrderOrList
= cirq.ops.QubitOrder.DEFAULT,
initial_state: Any = None
) -> Iterator
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. The form of this 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
simulate_sweep(
program: "cirq.Circuit",
params: cirq.study.Sweepable
,
qubit_order: cirq.ops.QubitOrderOrList
= cirq.ops.QubitOrder.DEFAULT,
initial_state: Any = None
) -> List['SimulationTrialResult']
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. The form of this 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. |