Add quilc_client property to QVMCompiler, improve timeout documentation (#1273)

* Add client property to QPUCompiler, improve timeout documentation

Add a client property to QPUCompiler so that it has better feature
parity with QVMCompiler. Generally we tell folks that

 1. QVMCompiler and QPUCompiler should be largely interchangeable,
 meaning that you can swap `qc = get_qc("Aspen-8", as_qvm=True)` with
 `qc = get_qc("Aspen-8", as_qvm=False)`, and things should Just
 Work. And

 2. To set the timeout on a QVMCompiler one does
 `qc.compiler.client.rpc_timeout = ...` but on a QPUCompiler
 `qc.compiler.quilc_client.rpc_timeout = ...`.

This change brings 1 and 2 into alignment, so that the method for
configuring the compiler timeout is the same between the compiler
classes.

* fix type

* Add set_timeout method to {QVM,QPU}Compiler classes

* fix doc

* Fix: send timeout value in native_quil_to_binary call

* Fix: set_timeout docstring

* Remove QPUCompiler#client in favour of QVMCompiler#quilc_client

* Remove some docs

* Remove comment

* Add compiler_timeout option to get_qc()

* Note timeout units

* oops

* type int -> float

* update changelog

* remove duplicate line

Co-authored-by: kalzoo <[email protected]>

Author: notmgsk

CHANGELOG.md

@@ -8,8 +8,14 @@ Changelog
 
 ### Improvements and Changes
 
-### Bugfixes
+- Timeout configuration has been revamped. `get_qc` now accepts a `compiler_timeout`
+  option, and `QVMCompiler` and `QPUCompiler` provide a `set_timeout` method, which should
+  greatly simplify the task of changing the default timeout. `QVMCompiler` also provides a
+  `quilc_client` property so that it shares the same interface as
+  `QPUCompiler`. Documentation has been updated to reflect these changes (@notmgsk,
+  @kalzoo, #1273).
 
+### Bugfixes
 
 [v2.24.0](https://github.com/rigetti/pyquil/compare/v2.23.1..v2.24.0) (November 5, 2020)
 ------------------------------------------------------------------------------------

docs/source/compiler.rst

@@ -113,6 +113,25 @@ the previous example snippet is identical to the following:
     ep = qc.compiler.native_quil_to_executable(np)
     print(ep.program) # here ep is of type PyquilExecutableResponse, which is not always inspectable
 
+Timeouts
+--------
+
+If your circuit is sufficiently complex the compiler may require more time than is permitted by
+default (``10`` seconds). To change this timeout, either use the `compiler_timeout` option to
+`get_qc`
+
+.. code:: python
+
+    qc = get_qc(..., compiler_timeout=100) # 100 seconds
+
+or use the `set_timeout` method on the compiler object:
+
+.. code:: python
+
+    qc = get_qc(...)
+    qc.compiler.set_timeout(100) # 100 seconds
+
+The timeout is specified in units of seconds.
 
 Legal compiler input
 --------------------

pyquil/api/_compiler.py

@@ -182,7 +182,7 @@ def __init__(
         quilc_endpoint: Optional[str],
         qpu_compiler_endpoint: Optional[str],
         device: AbstractDevice,
-        timeout: int = 10,
+        timeout: float = 10,
         name: Optional[str] = None,
         *,
         session: Optional[ForestSession] = None,
@@ -338,7 +338,9 @@ def native_quil_to_executable(self, nq_program: Program) -> Optional[BinaryExecu
         )
         response: BinaryExecutableResponse = cast(
             BinaryExecutableResponse,
-            self.qpu_compiler_client.call("native_quil_to_binary", request),
+            self.qpu_compiler_client.call(
+                "native_quil_to_binary", request, rpc_timeout=self.timeout
+            ),
         )
 
         # hack! we're storing a little extra info in the executable binary that we don't want to
@@ -356,6 +358,19 @@ def reset(self) -> None:
         """
         self._qpu_compiler_client = None
 
+    def set_timeout(self, timeout: float) -> None:
+        """
+        Set timeout for each individual stage of compilation.
+
+        :param timeout: Timeout value for each compilation stage, in seconds. If the stage does not
+            complete within this threshold, an exception is raised.
+        """
+        if timeout < 0:
+            raise ValueError(f"Cannot set timeout to negative value {timeout}")
+
+        self.timeout = timeout
+        self.quilc_client.rpc_timeout = timeout
+
 
 class QVMCompiler(AbstractCompiler):
     @_record_call
@@ -365,6 +380,8 @@ def __init__(self, endpoint: str, device: AbstractDevice, timeout: float = 10) -
 
         :param endpoint: TCP or IPC endpoint of the Compiler Server
         :param device: PyQuil Device object to use as compilation target
+        :param timeout: Timeout value for each compilation stage, in seconds. If the stage does not
+            complete within this threshold, an exception is raised.
         """
 
         if not endpoint.startswith("tcp://"):
@@ -428,6 +445,24 @@ def reset(self) -> None:
         self.client.close()  # type: ignore
         self.client = Client(self.endpoint, timeout=timeout)
 
+    @property
+    def quilc_client(self) -> Client:
+        """Return the `Client` for the compiler (i.e. quilc, not translation service)."""
+        return self.client
+
+    def set_timeout(self, timeout: float) -> None:
+        """
+        Set timeout for each individual stage of compilation.
+
+        :param timeout: Timeout value for each compilation stage, in seconds. If the stage does not
+            complete within this threshold, an exception is raised.
+        """
+        if timeout < 0:
+            raise ValueError(f"Cannot set timeout to negative value {timeout}")
+
+        self.timeout = timeout
+        self.quilc_client.rpc_timeout = timeout
+
 
 @dataclass
 class HTTPCompilerClient:
@@ -443,7 +478,7 @@ class HTTPCompilerClient:
     session: ForestSession
 
     def call(
-        self, method: str, payload: Optional[Message] = None, *, rpc_timeout: int = 30
+        self, method: str, payload: Optional[Message] = None, *, rpc_timeout: float = 30
     ) -> Message:
         """
         A partially-compatible implementation of rpcq.Client#call, which allows calling rpcq

pyquil/api/_quantum_computer.py

@@ -637,6 +637,7 @@ def _get_qvm_qc(
     noise_model: Optional[NoiseModel] = None,
     requires_executable: bool = False,
     connection: Optional[ForestConnection] = None,
+    compiler_timeout: float = 10,
 ) -> QuantumComputer:
     """Construct a QuantumComputer backed by a QVM.
 
@@ -666,7 +667,9 @@ def _get_qvm_qc(
             requires_executable=requires_executable,
         ),
         device=device,
-        compiler=QVMCompiler(device=device, endpoint=connection.compiler_endpoint),
+        compiler=QVMCompiler(
+            device=device, endpoint=connection.compiler_endpoint, timeout=compiler_timeout
+        ),
     )
 
 
@@ -677,6 +680,7 @@ def _get_qvm_with_topology(
     requires_executable: bool = True,
     connection: Optional[ForestConnection] = None,
     qvm_type: str = "qvm",
+    compiler_timeout: float = 10,
 ) -> QuantumComputer:
     """Construct a QVM with the provided topology.
 
@@ -709,11 +713,16 @@ def _get_qvm_with_topology(
         device=device,
         noise_model=noise_model,
         requires_executable=requires_executable,
+        compiler_timeout=compiler_timeout,
     )
 
 
 def _get_9q_square_qvm(
-    name: str, noisy: bool, connection: Optional[ForestConnection] = None, qvm_type: str = "qvm"
+    name: str,
+    noisy: bool,
+    connection: Optional[ForestConnection] = None,
+    qvm_type: str = "qvm",
+    compiler_timeout: float = 10,
 ) -> QuantumComputer:
     """
     A nine-qubit 3x3 square lattice.
@@ -735,6 +744,7 @@ def _get_9q_square_qvm(
         noisy=noisy,
         requires_executable=True,
         qvm_type=qvm_type,
+        compiler_timeout=compiler_timeout,
     )
 
 
@@ -744,6 +754,7 @@ def _get_unrestricted_qvm(
     n_qubits: int = 34,
     connection: Optional[ForestConnection] = None,
     qvm_type: str = "qvm",
+    compiler_timeout: float = 10,
 ) -> QuantumComputer:
     """
     A qvm with a fully-connected topology.
@@ -765,6 +776,7 @@ def _get_unrestricted_qvm(
         noisy=noisy,
         requires_executable=False,
         qvm_type=qvm_type,
+        compiler_timeout=compiler_timeout,
     )
 
 
@@ -774,6 +786,7 @@ def _get_qvm_based_on_real_device(
     noisy: bool,
     connection: Optional[ForestConnection] = None,
     qvm_type: str = "qvm",
+    compiler_timeout: float = 10,
 ) -> QuantumComputer:
     """
     A qvm with a based on a real device.
@@ -799,6 +812,7 @@ def _get_qvm_based_on_real_device(
         noise_model=noise_model,
         requires_executable=True,
         qvm_type=qvm_type,
+        compiler_timeout=compiler_timeout,
     )
 
 
@@ -809,6 +823,7 @@ def get_qc(
     as_qvm: Optional[bool] = None,
     noisy: Optional[bool] = None,
     connection: Optional[ForestConnection] = None,
+    compiler_timeout: float = 10,
 ) -> QuantumComputer:
     """
     Get a quantum computer.
@@ -877,6 +892,8 @@ def get_qc(
     :param connection: An optional :py:class:`ForestConnection` object. If not specified,
         the default values for URL endpoints will be used. If you deign to change any
         of these parameters, pass your own :py:class:`ForestConnection` object.
+    :param compiler_timeout: The number of seconds after which a compilation request will raise
+        a TimeoutError.
     :return: A pre-configured QuantumComputer
     """
     # 1. Parse name, check for redundant options, canonicalize names.
@@ -891,7 +908,12 @@ def get_qc(
         if qvm_type is None:
             raise ValueError("Please name a valid device or run as a QVM")
         return _get_unrestricted_qvm(
-            name=name, connection=connection, noisy=noisy, n_qubits=n_qubits, qvm_type=qvm_type
+            name=name,
+            connection=connection,
+            noisy=noisy,
+            n_qubits=n_qubits,
+            qvm_type=qvm_type,
+            compiler_timeout=compiler_timeout,
         )
 
     # 3. Check for "9q-square" qvm
@@ -901,14 +923,25 @@ def get_qc(
 
         if qvm_type is None:
             raise ValueError("The device '9q-square' is only available as a QVM")
-        return _get_9q_square_qvm(name=name, connection=connection, noisy=noisy, qvm_type=qvm_type)
+        return _get_9q_square_qvm(
+            name=name,
+            connection=connection,
+            noisy=noisy,
+            qvm_type=qvm_type,
+            compiler_timeout=compiler_timeout,
+        )
 
     # 4. Not a special case, query the web for information about this device.
     device = get_lattice(prefix)
     if qvm_type is not None:
         # 4.1 QVM based on a real device.
         return _get_qvm_based_on_real_device(
-            name=name, device=device, noisy=noisy, connection=connection, qvm_type=qvm_type
+            name=name,
+            device=device,
+            noisy=noisy,
+            connection=connection,
+            qvm_type=qvm_type,
+            compiler_timeout=compiler_timeout,
         )
     else:
         # 4.2 A real device
@@ -928,6 +961,7 @@ def get_qc(
             device=device,
             name=prefix,
             session=session,
+            timeout=compiler_timeout,
         )
 
         return QuantumComputer(name=name, qam=qpu, device=device, compiler=compiler)