Execution engine

Module name: strawberryfields.engine

This module implements BaseEngine and its subclasses that are responsible for communicating quantum programs represented by Program objects to a backend that could be e.g., a simulator or a hardware quantum processor. One can think of each BaseEngine instance as a separate quantum computation.

A typical use looks like

prog = sf.Program(num_subsystems)
with prog.context as q:
    Coherent(0.5)  | q[0]
    Vac            | q[1]
    Sgate(2)       | q[1]
    BSgate(1)      | q[0:2]
    Rgate(0.5)     | q[0]
    Dgate(0.5).H   | q[1]
    Measure        | q

eng = sf.LocalEngine(backend='fock', backend_options={'cutoff_dim': 5})
result = eng.run(prog)
assert prog.register[0].val == result.samples[0]

Classes

BaseEngine(backend[, backend_options]) ABC for quantum program executor engines.
LocalEngine(backend, *[, backend_options]) Local quantum program executor engine.
Result(samples) Result of a quantum computation.

LocalEngine methods

run(program, *[, compile_options, run_options]) Execute the given programs by sending them to the backend.
print_applied([print_fn]) Print all the Programs run since the backend was initialized.
reset([backend_options]) Re-initialize the quantum computation.

Exceptions

NotApplicableError Exception raised by the backend when the user attempts an unsupported operation.

Code details

class strawberryfields.engine.Result(samples)[source]

Result of a quantum computation.

Represents the results of the execution of a quantum program. Returned by BaseEngine.run().

samples

Measurement samples.

Returned measurement samples will have shape (modes,). If multiple shots are requested during execution, the returned measurement samples will instead have shape (shots, modes).

Returns:measurement samples returned from program execution
Return type:array[array[float, int]]
state

The quantum state object.

The quantum state object contains details and methods for manipulation of the final circuit state.

Note

Only local simulators will return a state object. Remote simulators and hardware backends will return measurement samples, but the return value of state will be None.

Returns:quantum state returned from program execution
Return type:BaseState
class strawberryfields.engine.BaseEngine(backend, backend_options=None)[source]

ABC for quantum program executor engines.

Parameters:
  • backend (str) – backend short name
  • backend_options (Dict[str, Any]) – keyword arguments for the backend
backend_name = None

short name of the backend

Type:str
backend_options = None

keyword arguments for the backend

Type:Dict[str, Any]
run_progs = None

list of Programs that have been run

Type:List[Program]
samples = None

latest measurement results, shape == (modes, shots)

Type:List[List[Number]]
reset(backend_options)[source]

Re-initialize the quantum computation.

Resets the state of the engine and the quantum circuit represented by the backend.

  • The original number of modes is restored.
  • All modes are reset to the vacuum state.
  • All RegRefs of previously run Programs are cleared of measured values.
  • List of previously run Progams is cleared.

Note that the reset does nothing to any Program objects in existence, beyond erasing the measured values.

Parameters:backend_options (Dict[str, Any]) – keyword arguments for the backend, updating (overriding) old values
print_applied(print_fn=<built-in function print>)[source]

Print all the Programs run since the backend was initialized.

This will be blank until the first call to run(). The output may differ compared to Program.print(), due to command decompositions and optimizations made by run().

Parameters:print_fn (function) – optional custom function to use for string printing.
_init_backend(init_num_subsystems)[source]

Initialize the backend.

Parameters:init_num_subsystems (int) – number of subsystems the backend is initialized to
_run_program(prog, **kwargs)[source]

Execute a single program on the backend.

This method should not be called directly.

Parameters:prog (Program) – program to run
Returns:commands that were applied to the backend
Return type:list[Command]
_run(program, *, compile_options=None, **kwargs)[source]

Execute the given programs by sending them to the backend.

If multiple Programs are given they will be executed sequentially as parts of a single computation. For each Program instance given as input, the following happens:

  • The Program instance is compiled for the target backend.
  • The compiled program is executed on the backend.
  • The measurement results of each subsystem (if any) are stored in the RegRef instances of the corresponding Program, as well as in samples.
  • The compiled program is appended to run_progs.

Finally, the result of the computation is returned.

Parameters:

The kwargs keyword arguments are passed to the backend API calls via Operation.apply().

Returns:results of the computation
Return type:Result
class strawberryfields.engine.LocalEngine(backend, *, backend_options=None)[source]

Local quantum program executor engine.

Executes Program instances on the chosen local backend, and makes the results available via Result.

Parameters:
  • backend (str, BaseBackend) – short name of the backend, or a pre-constructed backend instance
  • backend_options (None, Dict[str, Any]) – keyword arguments to be passed to the backend
backend = None

backend for executing the quantum circuit

Type:BaseBackend
reset(backend_options=None)[source]

Re-initialize the quantum computation.

Resets the state of the engine and the quantum circuit represented by the backend.

  • The original number of modes is restored.
  • All modes are reset to the vacuum state.
  • All RegRefs of previously run Programs are cleared of measured values.
  • List of previously run Progams is cleared.

Note that the reset does nothing to any Program objects in existence, beyond erasing the measured values.

Parameters:backend_options (Dict[str, Any]) – keyword arguments for the backend, updating (overriding) old values
_init_backend(init_num_subsystems)[source]

Initialize the backend.

Parameters:init_num_subsystems (int) – number of subsystems the backend is initialized to
_run_program(prog, **kwargs)[source]

Execute a single program on the backend.

This method should not be called directly.

Parameters:prog (Program) – program to run
Returns:commands that were applied to the backend
Return type:list[Command]
run(program, *, compile_options=None, run_options=None)[source]

Execute the given programs by sending them to the backend.

Extends BaseEngine._run().

Parameters:
  • program (Program, Sequence[Program]) – quantum programs to run
  • compile_options (None, Dict[str, Any]) – keyword arguments for Program.compile()
  • run_options (None, Dict[str, Any]) – keyword arguments that are needed by the backend during execution e.g., in Operation.apply() or BaseBackend.state()
Returns:

results of the computation

Return type:

Result

run_options can contain the following:

Keyword Arguments:
 
  • shots (int) – number of times the program measurement evaluation is repeated
  • modes (None, Sequence[int]) – Modes to be returned in the Result.state BaseState object. None returns all the modes (default). An empty sequence means no state object is returned.
  • eval (bool) – If False, the backend returns unevaluated tf.Tensors instead of numbers/arrays for returned measurement results and state (default: True). TF backend only.
  • session (tf.Session) – TensorFlow session, used when evaluating returned measurement results and state. TF backend only.
  • feed_dict (dict[str, Any]) – TensorFlow feed dictionary, used when evaluating returned measurement results and state. TF backend only.
strawberryfields.engine.Engine

alias of strawberryfields.engine.LocalEngine