cirq_google.calibration.PhasedFSimEngineSimulator

Wrapper on top of cirq.Simulator that allows to simulate calibration requests.

cirq_google.calibration.PhasedFSimEngineSimulator(
    simulator: cirq.Simulator,
    *,
    drift_generator: cirq_google.calibration.engine_simulator.ParametersDriftGenerator,
    gates_translator: Callable[[cirq.Gate], Optional[PhaseCalibratedFSimGate]] = cirq_google.calibration.try_convert_sqrt_iswap_to_fsim
) -> None

This simulator introduces get_calibrations which allows to simulate cirq_google.run_characterizations requests. The returned calibration results represent the internal state of a simulator. Circuits which are run on this simulator are modified to account for the changes in the unitary parameters as described by the calibration results.

simulator cirq.Simulator that all the simulation requests are delegated to.
drift_generator Callable that generates the imperfect parameters for each pair of qubits and the gate. They are later used for simulation.
gates_translator Function that translates a gate to a supported FSimGate which will undergo characterization.

gates_translator Function that translates a gate to a supported FSimGate which will undergo characterization.
noise

Methods

compute_amplitudes

compute_amplitudes(
    program: 'cirq.AbstractCircuit',
    bitstrings: Sequence[int],
    param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
    qubit_order: 'cirq.QubitOrderOrList' = 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. If inputting a binary literal add the prefix 0b or 0B. For example: 0010 can be input as 0b0010, 0B0010, 2, 0x2, etc.
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.AbstractCircuit',
    bitstrings: Sequence[int],
    params: 'cirq.Sweepable',
    qubit_order: 'cirq.QubitOrderOrList' = ops.QubitOrder.DEFAULT
) -> Sequence[Sequence[complex]]

Wraps computed amplitudes in a list.

Prefer overriding compute_amplitudes_sweep_iter.

compute_amplitudes_sweep_iter

compute_amplitudes_sweep_iter(
    program: 'cirq.AbstractCircuit',
    bitstrings: Sequence[int],
    params: 'cirq.Sweepable',
    qubit_order: 'cirq.QubitOrderOrList' = 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. If inputting a binary literal add the prefix 0b or 0B. For example: 0010 can be input as 0b0010, 0B0010, 2, 0x2, etc.
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.

create_from_characterizations_sqrt_iswap

View source

@classmethod
create_from_characterizations_sqrt_iswap(
    characterizations: Iterable[cirq_google.calibration.PhasedFSimCalibrationResult],
    *,
    simulator: Optional[cirq.Simulator] = None,
    ideal_when_missing_gate: bool = False,
    ideal_when_missing_parameter: bool = False
) -> 'PhasedFSimEngineSimulator'

Creates PhasedFSimEngineSimulator with fixed drifts from the characterizations results.

Args
characterizations Characterization results which are source of the parameters for each gate.
simulator Simulator object to use. When None, a new instance of cirq.Simulator() will be created.
ideal_when_missing_gate When set and parameters for some gate for a given pair of qubits are not specified in the parameters dictionary then the FSimGate(theta=π/4, phi=0) gate parameters will be used. When not set and this situation occurs, ValueError is thrown during simulation.
ideal_when_missing_parameter When set and some parameter for some gate for a given pair of qubits is specified then the matching parameter of FSimGate(theta=π/4, phi=0) gate will be used. When not set and this situation occurs, ValueError is thrown during simulation.

Returns
New PhasedFSimEngineSimulator instance.

Raises
ValueError If the gate was not a gate like ISWAP ** -0.5 or the pair of qubits it acts on appears in multiple different moments.

create_from_dictionary

View source

@classmethod
create_from_dictionary(
    parameters: Dict[Tuple[cirq.Qid, cirq.Qid], Dict[cirq.FSimGate, Union[
        PhasedFSimCharacterization, Dict]]],
    *,
    simulator: Optional[cirq.Simulator] = None
) -> 'PhasedFSimEngineSimulator'

Creates PhasedFSimEngineSimulator with fixed drifts.

Args
parameters maps every pair of qubits and engine gate on that pair to a characterization for that gate.
simulator Simulator object to use. When None, a new instance of cirq.Simulator() will be created.

Returns
New PhasedFSimEngineSimulator instance.

Raises
ValueError If missing parameters for the given pair of qubits.

create_from_dictionary_sqrt_iswap

View source

@classmethod
create_from_dictionary_sqrt_iswap(
    parameters: cirq_google.calibration.engine_simulator.PhasedFsimDictParameters,
    *,
    simulator: Optional[cirq.Simulator] = None,
    ideal_when_missing_gate: bool = False,
    ideal_when_missing_parameter: bool = False
) -> 'PhasedFSimEngineSimulator'

Creates PhasedFSimEngineSimulator with fixed drifts.

Args
parameters Parameters to use for each gate. All keys must be stored in canonical order, when the first qubit is not greater than the second one.
simulator Simulator object to use. When None, a new instance of cirq.Simulator() will be created.
ideal_when_missing_gate When set and parameters for some gate for a given pair of qubits are not specified in the parameters dictionary then the FSimGate(theta=π/4, phi=0) gate parameters will be used. When not set and this situation occurs, ValueError is thrown during simulation.
ideal_when_missing_parameter When set and some parameter for some gate for a given pair of qubits is specified then the matching parameter of FSimGate(theta=π/4, phi=0) gate will be used. When not set and this situation occurs, ValueError is thrown during simulation.

Returns
New PhasedFSimEngineSimulator instance.

Raises
ValueError If missing parameters for the given pair of qubits.

create_gate_with_drift

View source

create_gate_with_drift(
    a: cirq.Qid,
    b: cirq.Qid,
    gate_calibration: cirq_google.calibration.phased_fsim.PhaseCalibratedFSimGate
) -> cirq.PhasedFSimGate

Generates a gate with drift for a given gate.

Args
a The first qubit.
b The second qubit.
gate_calibration Reference gate together with a phase information.

Returns
A modified gate that includes the drifts induced by internal state of the simulator.

create_with_ideal_sqrt_iswap

View source

@classmethod
create_with_ideal_sqrt_iswap(
    *, simulator: Optional[cirq.Simulator] = None
) -> 'PhasedFSimEngineSimulator'

Creates a PhasedFSimEngineSimulator that simulates ideal FSimGate(theta=π/4, phi=0).

Attributes
simulator Simulator object to use. When None, a new instance of cirq.Simulator() will be created.

Returns
New PhasedFSimEngineSimulator instance.

create_with_random_gaussian_sqrt_iswap

View source

@classmethod
create_with_random_gaussian_sqrt_iswap(
    mean: cirq_google.calibration.PhasedFSimCharacterization = cirq_google.calibration.SQRT_ISWAP_INV_PARAMETERS,
    *,
    simulator: Optional[cirq.Simulator] = None,
    sigma: cirq_google.calibration.PhasedFSimCharacterization = PhasedFSimCharacterization(theta=0.02, zeta=0.05, chi=0.05, gamma=0.05, phi\n    =0.02),
    random_or_seed: cirq.RANDOM_STATE_OR_SEED_LIKE = None
) -> 'PhasedFSimEngineSimulator'

Creates a PhasedFSimEngineSimulator that introduces a random deviation from the mean.

The random deviations are described by a Gaussian distribution of a given mean and sigma, for each angle respectively.

Each gate for each pair of qubits retains the sampled values for the entire simulation, even when used multiple times within a circuit.

Attributes
mean The mean value for each unitary angle. All parameters must be provided.
simulator Simulator object to use. When None, a new instance of cirq.Simulator() will be created.
sigma The standard deviation for each unitary angle. For sigma parameters that are None, the mean value will be used without any sampling.

Returns
New PhasedFSimEngineSimulator instance.

Raises
ValueError If not all mean values were supplied.

final_state_vector

View source

final_state_vector(
    program: cirq.Circuit
) -> np.ndarray

get_calibrations

View source

get_calibrations(
    requests: Sequence[cirq_google.calibration.PhasedFSimCalibrationRequest]
) -> List[cirq_google.calibration.PhasedFSimCalibrationResult]

Retrieves the calibration that matches the requests

Args
requests Calibration requests to obtain.

Returns
Calibration results that reflect the internal state of simulator.

Raises
ValueError If supplied type of request is not supported or if the request contains and unsupported gate.

run

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

Samples from the given Circuit.

This mode of operation for a sampler will provide results in the form of measurement outcomes. It will not provide access to state vectors (even if the underlying sampling mechanism is a simulator). This method will substitute parameters in the param_resolver attributes for sympy.Symbols used within the Circuit. This circuit will be executed a number of times specified in the repetitions attribute, though some simulated implementations may instead sample from the final distribution rather than execute the circuit each time.

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

Returns
cirq.Result that contains all the measurements for a run.

run_async

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

Asynchronously samples from the given Circuit.

Provides measurement outcomes as a cirq.Result object. This interface will operate in a similar way to the run method except for executing asynchronously.

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

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

run_batch_async(
    programs, params_list=None, repetitions=1
)

Runs the supplied circuits asynchronously.

See docs for cirq.Sampler.run_batch.

run_sweep

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. The params argument will provide a mapping from sympy.Symbols used within the circuit to a set of values. Unlike the run method, which specifies a single mapping from symbol to value, this method allows a "sweep" of values. This allows a user to specify execution of a family of related circuits efficiently.

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

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

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

Samples the given Circuit, producing a pandas data frame.

This interface will operate in a similar way to the run method except that it returns a pandas data frame rather than a cirq.Result object.

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

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.observable_measurement.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.

sample_from_amplitudes

sample_from_amplitudes(
    circuit: 'cirq.AbstractCircuit',
    param_resolver: 'cirq.ParamResolver',
    seed: 'cirq.RANDOM_STATE_OR_SEED_LIKE',
    repetitions: int = 1,
    qubit_order: 'cirq.QubitOrderOrList' = ops.QubitOrder.DEFAULT
) -> Dict[int, int]

Uses amplitude simulation to sample from the given circuit.

This implements the algorithm outlined by Bravyi, Gosset, and Liu in https://arxiv.org/abs/2112.08499 to more efficiently calculate samples given an amplitude-based simulator.

Simulators which also implement SimulatesSamples or SimulatesFullState should prefer run() or simulate(), respectively, as this method only accelerates sampling for amplitude-based simulators.

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.

Returns
A dict of bitstrings sampled from the final state of circuit to the number of occurrences of that bitstring.

Raises
ValueError if 'circuit' has non-unitary elements, as differences in behavior between sampling steps break this algorithm.

simulate

View source

simulate(
    program: cirq.AbstractCircuit,
    param_resolver: cirq.ParamResolverOrSimilarType = None,
    qubit_order: cirq.QubitOrderOrList = cirq.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> cirq.StateVectorTrialResult

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.AbstractCircuit',
    param_resolver: 'cirq.ParamResolverOrSimilarType' = None,
    qubit_order: 'cirq.QubitOrderOrList' = ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> Iterator[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 TSimulationState. 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

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

Wraps computed states in a list.

Prefer overriding simulate_sweep_iter.

simulate_sweep_iter

simulate_sweep_iter(
    program: 'cirq.AbstractCircuit',
    params: 'cirq.Sweepable',
    qubit_order: 'cirq.QubitOrderOrList' = ops.QubitOrder.DEFAULT,
    initial_state: Any = None
) -> Iterator[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 SimulationStateBase. 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.