floq.client.simulators

floq.client.simulators.floq

This module provides interfaces for sending quantum circuits to the Floq service.

class floq.client.simulators.floq.AbstractRemoteSimulator(client: floq.client.api_client.ApiClient, handler: floq.client.sse.EventStreamHandler, endpoint: str, schema: marshmallow.schema.Schema)

Bases: abc.ABC

An abstract remote simulator.

This class contains core logic for sending simulation job context to the Floq service and fetching job results. The subclass, which provides concrete job type specialization, must implement its own run() method that reflects cirq specific simulator.

abstract run(*args, **kwargs) → Any

Runs a simulation.

Returns

Simulation result.

class floq.client.simulators.floq.ExpectationValuesSimulator(client: floq.client.api_client.ApiClient, handler: floq.client.sse.ExpectationJobStatusStreamHandler)

Bases: floq.client.simulators.floq.AbstractRemoteSimulator

Expectations values remote simulator.

run(circuit: cirq.circuits.circuit.Circuit, param_resolver: cirq.study.resolver.ParamResolver, observables: List[cirq.ops.linear_combinations.PauliSum]) → List[float]

Runs a simulation.

Parameters

  • circuit – The circuit to simulate.

  • param_resolver – Parameters to run with the program.

  • observables – PauliSums to compute expectations against.

Returns

A list of expectation values, with the value at index n corresponding to observables[n] from the input.

run_batch(circuits: List[cirq.circuits.circuit.Circuit], params: List[Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable]], observables: List[List[cirq.ops.linear_combinations.PauliSum]]) → List[List[List[float]]]

Runs a simulation.

Parameters

  • circuit – The circuit to simulate.

  • param_resolver – Parameters to run with the program. One sweepable per circuit.

  • observables – List of PauliSums to compute expectations against. One List of PauliSums per circuit.

Returns

A list of lists of lists of expectation values. The outer list corresponds to the circuit, the middle list corresponds to the parameter set generated from the Sweepable for that circuit, and the inner list corresponds to each observable provided for that circuit.

run_sweep(circuit: cirq.circuits.circuit.Circuit, params: Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable], observables: List[cirq.ops.linear_combinations.PauliSum]) → List[List[float]]

Runs a simulation.

Parameters

  • circuit – The circuit to simulate.

  • param_resolver – Parameters to run with the program.

  • observables – PauliSums to compute expectations against.

Returns

A list of lists of expectation values. The outer list corresponds to the parameter set generated from the Sweepable, and the inner list corresponds to each observable provided.

class floq.client.simulators.floq.SamplesSimulator(client: floq.client.api_client.ApiClient, handler: floq.client.sse.SampleJobStatusStreamHandler)

Bases: floq.client.simulators.floq.AbstractRemoteSimulator

Samples remote simulator.

run(circuit: cirq.circuits.circuit.Circuit, param_resolver: cirq.study.resolver.ParamResolver, repetitions: int) → cirq.study.result.Result

Runs a simulation.

Parameters

  • circuit – The circuit to simulate.

  • param_resolver – Parameters to run with the program.

  • repetitions – Number of times to repeat the run. It is expected that this is greater than 0.

Returns

A cirq.Result object.

run_batch(circuits: List[cirq.circuits.circuit.Circuit], params: List[Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable]], repetitions: Union[int, List[int]]) → List[List[cirq.study.result.Result]]

Runs a simulation.

Parameters

  • circuit – The circuit to simulate.

  • param_resolver – Parameters to run with the program.

  • repetitions – Number of times to repeat the run. It is expected that this is greater than 0.

Returns

List of lists of cirq.Result objects. The outer list corresponds to each circuit submitted and and the inner list corresponds to each parameter set generated from the Sweepable submitted for that circuit.

run_sweep(circuit: cirq.circuits.circuit.Circuit, params: Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable], repetitions: int) → List[cirq.study.result.Result]

Runs a simulation.

Parameters

  • circuit – The circuit to simulate.

  • param_resolver – Parameters to run with the program.

  • repetitions – Number of times to repeat the run. It is expected that this is greater than 0.

Returns

List of cirq.Result objects.

class floq.client.simulators.floq.SimulationProgressThread(size: int)

Bases: threading.Thread

Displays simulation job progress status.

This class uses progressbar.ProgressBar to display simulation job progress. Every time the Floq service finish simulating a work item it sends a status event. Between events we need to manually force refresh the bar to update elapsed timer widget.

finalize() → None

Finalizes the thread.

Stops thread main loop and sends notification to the progress bar.

run() → None

See base class documentation.

update(current: int, total: int) → None

Sets a new progress value.

Parameters

  • current – Number of completed work items.

  • total – Total number of work items.

floq.client.simulators.cirq

This module provides cirq based implementation of the Floq service simulators.

class floq.client.simulators.cirq.CirqSimulator(simulators: Dict[floq.client.schemas.JobType, floq.client.simulators.floq.AbstractRemoteSimulator])

Bases: cirq.sim.simulator.SimulatesSamples, cirq.sim.simulator.SimulatesExpectationValues

A cirq based remote simulator.

Simulates quantum circuits on the cloud and provides interfaces of following Cirq simulators:

Note: The simulator does not support cirq.sim.simulator.SimulatesSamples asynchronous methods - they behave same way as the synchronous methods.

run(program: cirq.circuits.circuit.Circuit, param_resolver: Optional[Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]]]] = None, repetitions: int = 1) → cirq.study.result.Result

Samples from the given Circuit.

Parameters

  • 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(programs: List[cirq.circuits.circuit.Circuit], params_list: Optional[List[Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable]]] = None, repetitions: Union[int, List[int]] = 1) → List[List[cirq.study.result.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.

Parameters

  • 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_iter(program: cirq.circuits.circuit.Circuit, params: Union[cirq.study.resolver.ParamResolver, Dict[Union[str, sympy.core.basic.Basic], Union[float, sympy.core.basic.Basic]], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable], repetitions: int = 1) → Iterator[cirq.study.result.Result]

Runs the supplied Circuit, mimicking quantum hardware.

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

Parameters

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

simulate_expectation_values(program: cirq.circuits.circuit.Circuit, observables: Union[int, float, complex, cirq.ops.pauli_string.PauliString, PauliSum, cirq.ops.pauli_string.SingleQubitPauliStringGateOperation, List[Union[int, float, complex, cirq.ops.pauli_string.PauliString, PauliSum, cirq.ops.pauli_string.SingleQubitPauliStringGateOperation]]], param_resolver: Optional[Union[cirq.ParamResolver, Dict[cirq.TParamKey, cirq.TParamVal]]] = None, qubit_order: Union[cirq.ops.qubit_order.QubitOrder, Iterable[cirq.ops.raw_types.Qid]] = <cirq.ops.qubit_order.QubitOrder object>, initial_state: Any = None, permit_terminal_measurements: bool = True) → 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.

Parameters

  • 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_batch(programs: List[cirq.circuits.circuit.Circuit], observables_list: List[List[Union[int, float, complex, cirq.ops.pauli_string.PauliString, PauliSum, cirq.ops.pauli_string.SingleQubitPauliStringGateOperation]]], params_list: List[Union[cirq.ParamResolver, Dict[cirq.TParamKey, cirq.TParamVal], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable]], qubit_order: Union[cirq.ops.qubit_order.QubitOrder, Iterable[cirq.ops.raw_types.Qid]] = <cirq.ops.qubit_order.QubitOrder object>, initial_state: Any = None, permit_terminal_measurements: bool = True) → List[List[List[float]]]

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

This method expects a list of observables and a sweepable for each circuit.

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

Parameters

  • programs – A list of circuits to simulate.

  • observables_list – A list of observables for each circuit.

  • params_list – A Sweepable for each circuit.

  • 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

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

simulate_expectation_values_sweep(program: cirq.circuits.circuit.Circuit, observables: Union[int, float, complex, cirq.ops.pauli_string.PauliString, PauliSum, cirq.ops.pauli_string.SingleQubitPauliStringGateOperation, List[Union[int, float, complex, cirq.ops.pauli_string.PauliString, PauliSum, cirq.ops.pauli_string.SingleQubitPauliStringGateOperation]]], params: Union[cirq.ParamResolver, Dict[cirq.TParamKey, cirq.TParamVal], None, cirq.study.sweeps.Sweep, cirq.study.sweepable._Sweepable], qubit_order: Union[cirq.ops.qubit_order.QubitOrder, Iterable[cirq.ops.raw_types.Qid]] = <cirq.ops.qubit_order.QubitOrder object>, initial_state: Any = None, permit_terminal_measurements: bool = True) → List[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.

Parameters

  • 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

A list of expectation-value. 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 theR second sweep.