Unify RemoteEngine.run() and LocalEngine.run() signatures, and allow for default chip specs for each device family.

[josh146]

Context:

Currently in Strawberry Fields:

• The user must initialize an engine or a compile a program with a specific chip target, e.g., X8_01, X12_01, etc. However, there should be a way for the user to initialize an engine or compile a program for a chip family (e.g., eng.run("X8"), prog.compile("X8")), with the Remote engine delegating the job to a specified default for each family.

• LocalEngine.run() and RemoteEngine.run() have inconsistent signatures:

  LocalEngine.run(self, program, *, args=None, compile_options=None, run_options=None)
  RemoteEngine.run(self, program: Program, shots: Optional[int] = None)

While these appear as two separate issues, they are quite interconnected. Since eng.run() internally calls the prog.compile() method, both engines must keep track and pass on any run_options that the user specifies so that they can be taken into account during compilation/execution.

Description of the Change:

• The base X8Spec and X12Spec specifications are now included in the Strawberry Fields circuit spec database, with short names X8 and X12 respectively. Programs that are compiled against these specs, e.g., prog.compile("X8") have prog.target == "X8".

• The RemoteEngine can now be instantiated with targets "X8" and "X12".

• The RemoteEngine has a class attribute

  DEFAULT_TARGETS = {"X8": "X8_01", "X12": "X12_01"}

  which specifies the default chip to target for each device family. Hardcoding this is a temporary fix, and will be removed once the chip API is online.

• For now, since only chip family compilation is available (i.e., there is no chip specific compilation), compiling against either "X8" and "X8_01" makes no difference. Therefore, eng=RemoteEngine("X8") will only recompile a program if program.target[:2] != "X8".

• Old references to REMOTE in the BaseEngine have been removed, since RemoteEngine no longer inherits from BaseEngine.

• RemoteEngine.run() and LocalEngine.run() signatures have both been standardized to the following:

  run(run(self, program, *, args=None, compile_options=None, **run_options)

  This is a compromise that aims to balance a nicer, more consistent UI against internal behaviour. In particular:

  • The run_options={} dictionary argument from the LocalEngine has been changed to **run_options. This allows for the syntax eng.run(prog, shots=100), which is cleaner and more intutive than eng.run(prog, run_options={"shots": 100}).

  • compile_options={} dictionary argument has been added to the RemoteEngine, as well as compilation (previously the remote engine was not validating/compiling programs).

• RunEngine.__init__() now takes a backend_options={} argument, allowing backend options to be set. This is not needed currently, but will be needed for remote simulators (e.g., passing cutoff dimension).

• The Connection.create_job() method has been updated to send all run and backend options, rather than just shots (useful for future compatibility with remote simulators).

Benefits: see above.

Possible Drawbacks:

• Currently, compiling a program against "X8" and "X8_01" makes no difference. However, in the future, compiling against "X8" will compile to match the (static) family architecture, while X8_01 will compile to match (dynamic) specific hardware constraints of chip 01 from the API service.

• Hardcoding of the default chip specs is temporary, and will be removed once a chip API is online.

Related GitHub Issues:

• Fixes #335
• Will allow implementation of suggested changes from #334

[thisac]

The tests fail because of the new run_options convention. I created a new branch where I've updated all of the instances of run_options as dictionaries, e.g. run_options={"shots": shots}, to keyword arguments instead. I'm not sure if this is the easiest way to fix this, though. Please tell me if I should rather create a separate PR for this.

The branch with all the changes is called shots_as_kwargs, and should fix the run_options in all files (including tutorials and documentation).

[codecov[bot]]

Codecov Report

Merging #337 into master will increase coverage by 0.00%. The diff coverage is 99.23%.

@@           Coverage Diff           @@
##           master     #337   +/-   ##
=======================================
  Coverage   97.69%   97.70%           
=======================================
  Files          51       51           
  Lines        6346     6354    +8     
=======================================
+ Hits         6200     6208    +8     
  Misses        146      146           

Impacted Files	Coverage Δ
strawberryfields/io.py	98.78% <66.66%> (-1.22%)	:arrow_down:
strawberryfields/api/connection.py	97.70% <100.00%> (+0.02%)	:arrow_up:
strawberryfields/apps/sample.py	100.00% <100.00%> (ø)
strawberryfields/circuitspecs/X12.py	100.00% <100.00%> (ø)
strawberryfields/circuitspecs/X8.py	100.00% <100.00%> (ø)
strawberryfields/circuitspecs/__init__.py	100.00% <100.00%> (ø)
strawberryfields/engine.py	95.33% <100.00%> (+0.77%)	:arrow_up:
strawberryfields/program.py	98.84% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 605819a...64c850c. Read the comment docs.