feat!: QVM timeout can now be configured via a new options parameter (#309)

* feat!: QVM timeout can now be configured via a new options parameter

* use Duration:from_secs for QVM_DEFAULT_TIMEOUT

Author: MarquessV

crates/lib/src/executable.rs

@@ -679,7 +679,9 @@ impl From<ExecutionError> for Error {
 impl From<qvm::Error> for Error {
     fn from(err: qvm::Error) -> Self {
         match err {
-            qvm::Error::QvmCommunication { .. } => Self::Connection(Service::Qvm),
+            qvm::Error::QvmCommunication { .. } | qvm::Error::Client { .. } => {
+                Self::Connection(Service::Qvm)
+            }
             qvm::Error::Parsing(_)
             | qvm::Error::ShotsMustBePositive
             | qvm::Error::RegionSizeMismatch { .. }

crates/lib/src/qvm/api.rs

@@ -8,7 +8,7 @@ use serde::{de::DeserializeOwned, Deserialize, Serialize};
 
 use crate::{client::Qcs, RegisterData};
 
-use super::Error;
+use super::{Error, QvmOptions};
 
 #[derive(Serialize, Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq)]
 #[serde(rename_all = "kebab-case")]
@@ -54,11 +54,11 @@ impl<T: DeserializeOwned> QvmResponse<T> {
 }
 
 /// Fetch the version information from the running QVM server.
-pub async fn get_version_info(client: &Qcs) -> Result<String, Error> {
+pub async fn get_version_info(client: &Qcs, options: &QvmOptions) -> Result<String, Error> {
     #[cfg(feature = "tracing")]
     tracing::debug!("requesting qvm version information");
     let params = HashMap::from([("type", "version")]);
-    let response = make_request(&params, client).await?;
+    let response = make_request(&params, client, options).await?;
     let qvm_url = client.get_config().qvm_url().into();
     if response.status() == 200 {
         response
@@ -74,10 +74,14 @@ pub async fn get_version_info(client: &Qcs) -> Result<String, Error> {
 }
 
 /// Executes a program on the QVM.
-pub async fn run(request: &MultishotRequest, client: &Qcs) -> Result<MultishotResponse, Error> {
+pub async fn run(
+    request: &MultishotRequest,
+    client: &Qcs,
+    options: &QvmOptions,
+) -> Result<MultishotResponse, Error> {
     #[cfg(feature = "tracing")]
     tracing::debug!("making a multishot request to the QVM");
-    let response = make_request(request, client).await?;
+    let response = make_request(request, client, options).await?;
     response
         .json::<QvmResponse<MultishotResponse>>()
         .await
@@ -174,8 +178,9 @@ pub struct MultishotResponse {
 pub async fn run_and_measure(
     request: &MultishotMeasureRequest,
     client: &Qcs,
+    options: &QvmOptions,
 ) -> Result<Vec<Vec<i64>>, Error> {
-    let response = make_request(request, client).await?;
+    let response = make_request(request, client, options).await?;
     response
         .json::<QvmResponse<Vec<Vec<i64>>>>()
         .await
@@ -236,8 +241,9 @@ impl MultishotMeasureRequest {
 pub async fn measure_expectation(
     request: &ExpectationRequest,
     client: &Qcs,
+    options: &QvmOptions,
 ) -> Result<Vec<f64>, Error> {
-    let response = make_request(request, client).await?;
+    let response = make_request(request, client, options).await?;
     response
         .json::<QvmResponse<Vec<f64>>>()
         .await
@@ -280,8 +286,9 @@ impl ExpectationRequest {
 pub async fn get_wavefunction(
     request: &WavefunctionRequest,
     client: &Qcs,
+    options: &QvmOptions,
 ) -> Result<Vec<u8>, Error> {
-    let response = make_request(request, client).await?;
+    let response = make_request(request, client, options).await?;
     if response.status() == 200 {
         response
             .bytes()
@@ -340,12 +347,18 @@ impl WavefunctionRequest {
     }
 }
 
-async fn make_request<T>(request: &T, client: &Qcs) -> Result<Response, Error>
+async fn make_request<T>(request: &T, client: &Qcs, options: &QvmOptions) -> Result<Response, Error>
 where
     T: Serialize,
 {
     let qvm_url = client.get_config().qvm_url();
-    let client = reqwest::Client::new();
+    let mut client = reqwest::Client::new();
+    if let Some(timeout) = options.timeout {
+        client = reqwest::Client::builder()
+            .timeout(timeout)
+            .build()
+            .map_err(Error::Client)?;
+    }
     client
         .post(qvm_url)
         .json(request)

crates/lib/src/qvm/execution.rs

@@ -7,6 +7,7 @@ use crate::{executable::Parameters, qvm::run_program};
 
 use crate::client::Qcs;
 
+use super::QvmOptions;
 use super::{api::AddressRequest, Error, QvmResultData};
 
 /// Contains all the info needed to execute on a QVM a single time, with the ability to be reused for
@@ -69,6 +70,7 @@ impl Execution {
             None,
             None,
             client,
+            &QvmOptions::default(),
         )
         .await
     }

crates/lib/src/qvm/mod.rs

@@ -1,7 +1,7 @@
 //! This module contains all the functionality for running Quil programs on a QVM. Specifically,
 //! the [`Execution`] struct in this module.
 
-use std::{collections::HashMap, num::NonZeroU16, str::FromStr};
+use std::{collections::HashMap, num::NonZeroU16, str::FromStr, time::Duration};
 
 use quil_rs::{
     instruction::{ArithmeticOperand, Instruction, MemoryReference, Move},
@@ -19,6 +19,9 @@ use self::api::AddressRequest;
 pub mod api;
 mod execution;
 
+/// Number of seconds to wait before timing out.
+const DEFAULT_QVM_TIMEOUT: Duration = Duration::from_secs(30);
+
 /// Encapsulates data returned after running a program on the QVM
 #[allow(clippy::module_name_repetitions)]
 #[derive(Debug, Deserialize, Clone, PartialEq)]
@@ -52,6 +55,7 @@ pub async fn run(
     gate_noise: Option<(f64, f64, f64)>,
     rng_seed: Option<i64>,
     client: &Qcs,
+    options: &QvmOptions,
 ) -> Result<QvmResultData, Error> {
     #[cfg(feature = "tracing")]
     tracing::debug!("parsing a program to be executed on the qvm");
@@ -65,6 +69,7 @@ pub async fn run(
         gate_noise,
         rng_seed,
         client,
+        options,
     )
     .await
 }
@@ -81,6 +86,7 @@ pub async fn run_program(
     gate_noise: Option<(f64, f64, f64)>,
     rng_seed: Option<i64>,
     client: &Qcs,
+    options: &QvmOptions,
 ) -> Result<QvmResultData, Error> {
     #[cfg(feature = "tracing")]
     tracing::debug!(
@@ -98,7 +104,7 @@ pub async fn run_program(
         gate_noise,
         rng_seed,
     );
-    api::run(&request, client)
+    api::run(&request, client, options)
         .await
         .map(|response| QvmResultData::from_memory_map(response.registers))
 }
@@ -147,6 +153,33 @@ pub fn apply_parameters_to_program(
     Ok(program)
 }
 
+/// Options avaialable for running programs on the QVM.
+#[allow(clippy::module_name_repetitions)]
+#[derive(Clone, Copy, Debug)]
+pub struct QvmOptions {
+    /// The timeout to use for requests to the QVM. If set to [`None`], there is no timeout.
+    pub timeout: Option<Duration>,
+}
+
+impl QvmOptions {
+    /// Builds a [`QvmOptions`] with the zero value for each option.
+    ///
+    /// Consider using [`Default`] to get a reasonable set of
+    /// configuration options as a starting point.
+    #[must_use]
+    pub fn new() -> Self {
+        Self { timeout: None }
+    }
+}
+
+impl Default for QvmOptions {
+    fn default() -> Self {
+        Self {
+            timeout: Some(DEFAULT_QVM_TIMEOUT),
+        }
+    }
+}
+
 /// All of the errors that can occur when running a Quil program on QVM.
 #[allow(missing_docs)]
 #[derive(Debug, thiserror::Error)]
@@ -170,6 +203,8 @@ pub enum Error {
     },
     #[error("QVM reported a problem running your program: {message}")]
     Qvm { message: String },
+    #[error("The client failed to make the request: {0}")]
+    Client(#[from] reqwest::Error),
 }
 
 #[cfg(test)]

crates/lib/tests/qvm_api.rs

@@ -3,7 +3,10 @@
 
 use std::{collections::HashMap, num::NonZeroU16};
 
-use qcs::{client::Qcs, qvm::api};
+use qcs::{
+    client::Qcs,
+    qvm::{api, QvmOptions},
+};
 use regex::Regex;
 
 const PROGRAM: &str = r##"
@@ -16,7 +19,7 @@ MEASURE 1 ro[1]
 
 #[tokio::test]
 async fn test_get_version_info() {
-    let version = api::get_version_info(&Qcs::default())
+    let version = api::get_version_info(&Qcs::default(), &QvmOptions::default())
         .await
         .expect("Should be able to get version info.");
     let semver_re = Regex::new(r"^([0-9]+)\.([0-9]+)\.([0-9]+)").unwrap();
@@ -34,7 +37,7 @@ async fn test_run() {
         Some((0.1, 0.5, 0.4)),
         Some(1),
     );
-    let response = api::run(&request, &client)
+    let response = api::run(&request, &client, &QvmOptions::default())
         .await
         .expect("Should be able to run");
     assert_eq!(response.registers.len(), 1);
@@ -57,7 +60,7 @@ async fn test_run_and_measure() {
         Some((0.1, 0.5, 0.4)),
         Some(1),
     );
-    let qubits = api::run_and_measure(&request, &client)
+    let qubits = api::run_and_measure(&request, &client, &QvmOptions::default())
         .await
         .expect("Should be able to run and measure");
     assert_eq!(qubits.len(), 5);
@@ -75,7 +78,7 @@ Z 2
     let operators = vec!["X 0\nY 1\n".to_string(), "Z 2\n".to_string()];
     let request = api::ExpectationRequest::new(prep_program.to_string(), &operators, None);
 
-    let expectations = api::measure_expectation(&request, &client)
+    let expectations = api::measure_expectation(&request, &client, &QvmOptions::default())
         .await
         .expect("Should be able to measure expectation");
 
@@ -86,7 +89,7 @@ Z 2
 async fn test_get_wavefunction() {
     let client = Qcs::default();
     let request = api::WavefunctionRequest::new(PROGRAM.to_string(), None, None, Some(0));
-    api::get_wavefunction(&request, &client)
+    api::get_wavefunction(&request, &client, &QvmOptions::default())
         .await
         .expect("Should be able to get wavefunction");
 }

crates/python/qcs_sdk/qvm/__init__.pyi

@@ -25,6 +25,30 @@ class QVMResultData:
         """
         ...
 
+@final
+class QVMOptions:
+    """
+    Options avaialable for running programs on the QVM.
+    """
+
+    def __new__(cls, timeout_seconds: Optional[float] = None) -> QVMOptions: ...
+    @staticmethod
+    def default() -> QVMOptions:
+        """Get the default set of ``QVMOptions`` used for QVM requests.
+
+        Settings:
+            timeout: 30.0 seconds
+        """
+        ...
+    @property
+    def timeout(cls):
+        """The timeout used for reqeusts to the QVM. If set to none, there is no timeout."""
+        ...
+    @timeout.setter
+    def timeout(cls, timeout: Optional[float]):
+        """The timeout used for reqeusts to the QVM. If set to none, there is no timeout."""
+        ...
+
 @final
 class QVMError(RuntimeError):
     """
@@ -42,6 +66,7 @@ def run(
     gate_noise: Optional[Tuple[float, float, float]] = None,
     rng_seed: Optional[int] = None,
     client: Optional[QCSClient] = None,
+    options: Optional[QVMOptions] = None,
 ) -> QVMResultData:
     """
     Runs the given program on the QVM.
@@ -51,6 +76,7 @@ def run(
     :param addresses: A mapping of memory region names to an ``AddressRequest`` describing what data to get back for that memory region from the QVM at the end of execution.
     :param params: A mapping of memory region names to their desired values.
     :param client: An optional ``QCSClient`` to use. If unset, creates one using the environemnt configuration (see https://docs.rigetti.com/qcs/references/qcs-client-configuration).
+    :param options: An optional ``QVMOptions`` to use. If unset, uses ``QVMOptions.default()`` for the request.
 
     :returns: A ``QVMResultData`` containing the final state of of memory for the requested readouts after the program finished running.
 
@@ -67,6 +93,7 @@ async def run_async(
     gate_noise: Optional[Tuple[float, float, float]] = None,
     rng_seed: Optional[int] = None,
     client: Optional[QCSClient] = None,
+    options: Optional[QVMOptions] = None,
 ) -> QVMResultData:
     """
     Asynchronously runs the given program on the QVM.
@@ -76,6 +103,7 @@ async def run_async(
     :param addresses: A mapping of memory region names to an ``AddressRequest`` describing what data to get back for that memory region from the QVM at the end of execution.
     :param params: A mapping of memory region names to their desired values.
     :param client: An optional ``QCSClient`` to use. If unset, creates one using the environemnt configuration (see https://docs.rigetti.com/qcs/references/qcs-client-configuration).
+    :param options: An optional ``QVMOptions`` to use. If unset, uses ``QVMOptions.default()`` for the request.
 
     :returns: A ``QVMResultData`` containing the final state of of memory for the requested readouts after the program finished running.