Add optional memory_map parameter to QuantumComputer.run (rigetti#657)

docs/source/migration.rst

@@ -390,20 +390,14 @@ becomes
 .. code:: python
 
     # set up the Program object, ONLY ONCE
-    program = build_wf_ansatz_prep()
-    program.wrap_in_numshots_loop(shots=shots)
-    nq_program = qc.compiler.quil_to_native_quil(program)
-    binary = qc.compiler.native_quil_to_executable(nq_program)
-    qc.qam.load(binary)
+    program = build_wf_ansatz_prep().wrap_in_numshots_loop(shots=shots)
+    binary = qc.compile(program)
 
     # get all the unweighted expectations for all the sample wavefunctions
     occupations = list(range(angle_min, angle_max))
     indices = list(range(4))
     for offset in occupations:
-        qc.qam.write_memory(region_name='theta', value=angle_min + offset * angle_step)
-        qc.qam.run()
-        qc.qam.wait()
-        bitstrings = qc.qam.read_memory(region_name="ro")
+        bitstrings = qc.run(binary, {'theta': [angle_min + offset * angle_step]})
 
         totals = [0, 0, 0, 0]
         for bitstring in bitstrings:
@@ -472,20 +466,14 @@ Overall, the resulting program looks like this:
     qc = setup_forest_objects()
 
     # set up the Program object, ONLY ONCE
-    program = build_wf_ansatz_prep()
-    program.wrap_in_numshots_loop(shots=shots)
-    nq_program = qc.compiler.quil_to_native_quil(program)
-    binary = qc.compiler.native_quil_to_executable(nq_program)
-    qc.qam.load(binary)
+    program = build_wf_ansatz_prep().wrap_in_numshots_loop(shots=shots)
+    binary = qc.compile(program)
 
     # get all the unweighted expectations for all the sample wavefunctions
     occupations = list(range(angle_min, angle_max))
     indices = list(range(4))
     for offset in occupations:
-        qc.qam.write_memory(region_name='theta', value=angle_min + offset * angle_step)
-        qc.qam.run()
-        qc.qam.wait()
-        bitstrings = qc.qam.read_memory(region_name="ro")
+        bitstrings = qc.run(binary, {'theta': [angle_min + offset * angle_step]})
 
         totals = [0, 0, 0, 0]
         for bitstring in bitstrings:

pyquil/api/_quantum_computer.py

@@ -142,17 +142,26 @@ def get_isa(self, oneq_type: str = 'Xhalves',
         return self.device.get_isa(oneq_type=oneq_type, twoq_type=twoq_type)
 
     @_record_call
-    def run(self, executable: Executable) -> np.ndarray:
+    def run(self, executable: Executable,
+            memory_map: Dict[str, List[Union[int, float]]] = None) -> np.ndarray:
         """
-        Run a quil executable.
+        Run a quil executable. If the executable contains declared parameters, then a memory
+        map must be provided, which defines the runtime values of these parameters.
 
         :param executable: The program to run. You are responsible for compiling this first.
-        :return: A numpy array of shape (trials, len(ro-register)) that contains 0s and 1s
+        :param memory_map: The mapping of declared parameters to their values. The values
+            are a list of floats or integers.
+        :return: A numpy array of shape (trials, len(ro-register)) that contains 0s and 1s.
         """
-        return self.qam.load(executable) \
-            .run() \
+        self.qam.load(executable)
+        if memory_map:
+            for region_name, values_list in memory_map.items():
+                for offset, value in enumerate(values_list):
+                    # TODO gh-658: have write_memory take a list rather than value + offset
+                    self.qam.write_memory(region_name=region_name, offset=offset, value=value)
+        return self.qam.run() \
             .wait() \
-            .read_memory(region_name="ro")
+            .read_memory(region_name='ro')
 
     @_record_call
     def run_symmetrized_readout(self, program: Program, trials: int) -> np.ndarray:

pyquil/tests/test_quantum_computer.py

@@ -10,6 +10,7 @@
 from pyquil.api._quantum_computer import _get_flipped_protoquil_program, _parse_name
 from pyquil.device import NxDevice, gates_in_isa
 from pyquil.gates import *
+from pyquil.quilbase import Declare, MemoryReference
 from pyquil.noise import decoherence_noise_with_asymmetric_ro
 from rpcq.messages import PyQuilExecutableResponse
 
@@ -319,3 +320,25 @@ def test_qvm_compile_pickiness(forest):
 
     # Yot ok
     qc.run(nq)
+
+
+def test_run_with_parameters(forest):
+    device = NxDevice(nx.complete_graph(3))
+    qc = QuantumComputer(
+        name='testy!',
+        qam=QVM(connection=forest),
+        device=device,
+        compiler=DummyCompiler()
+    )
+    bitstrings = qc.run(
+        executable=Program(
+            Declare(name='theta', memory_type='REAL'),
+            Declare(name='ro', memory_type='BIT'),
+            RX(MemoryReference('theta'), 0),
+            MEASURE(0, MemoryReference('ro'))
+        ).wrap_in_numshots_loop(1000),
+        memory_map={'theta': [np.pi]}
+    )
+
+    assert bitstrings.shape == (1000, 1)
+    assert all([bit == 1 for bit in bitstrings])