feat(python): support TranslationOptions

crates/lib/src/qpu/translation.rs

@@ -6,8 +6,9 @@ use std::{collections::HashMap, time::Duration};
 use qcs_api_client_grpc::{
     models::controller::EncryptedControllerJob,
     services::translation::{
-        translate_quil_to_encrypted_controller_job_request::NumShots,
-        TranslateQuilToEncryptedControllerJobRequest, TranslationOptions,
+        self, translate_quil_to_encrypted_controller_job_request::NumShots,
+        translation_options::TranslationBackend, TranslateQuilToEncryptedControllerJobRequest,
+        TranslationOptions as RdmTranslationOptions,
     },
 };
 use qcs_api_client_openapi::{
@@ -33,25 +34,30 @@ pub struct EncryptedTranslationResult {
 }
 
 /// Translate a program, returning an encrypted and translated program.
-pub async fn translate(
+pub async fn translate<TO>(
     quantum_processor_id: &str,
     quil_program: &str,
     num_shots: u32,
     client: &Qcs,
-    translation_options: Option<TranslationOptions>,
-) -> Result<EncryptedTranslationResult, GrpcClientError> {
+    translation_options: TO,
+) -> Result<EncryptedTranslationResult, GrpcClientError>
+where
+    TO: Into<Option<RdmTranslationOptions>>,
+{
     #[cfg(feature = "tracing")]
     tracing::debug!(
         %num_shots,
         "translating program for {}",
         quantum_processor_id,
     );
 
+    let options = translation_options.into();
+
     let request = TranslateQuilToEncryptedControllerJobRequest {
         quantum_processor_id: quantum_processor_id.to_owned(),
         num_shots: Some(NumShots::NumShotsValue(num_shots)),
         quil_program: quil_program.to_owned(),
-        options: translation_options,
+        options,
     };
 
     let response = client
@@ -104,3 +110,32 @@ pub async fn get_quilt_calibrations(
     })
     .await?
 }
+
+/// Options available for Quil program translation.
+/// 
+/// This wraps [`RdmTranslationOptions`] in order to improve the user experience,
+/// because the structs auto-generated by `prost` can be clumsy to use directly.
+#[derive(Debug, Default)]
+pub struct TranslationOptions {
+    inner: RdmTranslationOptions,
+}
+
+impl TranslationOptions {
+    /// Use the first-generation translation backend available on QCS since 2018.
+    pub fn use_backend_v1(&mut self) {
+        self.inner.translation_backend =
+            Some(TranslationBackend::V1(translation::BackendV1Options {}))
+    }
+
+    /// Use the second-generation translation backend available on QCS since 2023
+    pub fn use_backend_v2(&mut self) {
+        self.inner.translation_backend =
+            Some(TranslationBackend::V2(translation::BackendV2Options {}))
+    }
+}
+
+impl From<TranslationOptions> for RdmTranslationOptions {
+    fn from(options: TranslationOptions) -> Self {
+        options.inner
+    }
+}

crates/python/qcs_sdk/grpc/models/translation.pyi

@@ -0,0 +1,45 @@
+from typing import Optional, final
+
+class TranslationOptions:
+    translation_backend: Optional[TranslationBackend] = None
+
+    ...
+
+@final
+class TranslationBackend:
+    """
+    Object specifying which translation backend to use to translate a particular program,
+    and for that given backend, what options to apply.
+
+    Variants:
+        ``v1``: Corresponds to the V1 translation backend.
+        ``v2``: Corresponds to the V2 translation backend.
+
+    Methods (each per variant):
+        - ``is_*``: if the underlying values are that type.
+        - ``as_*``: if the underlying values are that type, then those values, otherwise ``None``.
+        - ``to_*``: the underlying values as that type, raises ``ValueError`` if they are not.
+        - ``from_*``: wrap underlying values as this enum type.
+
+    """
+
+    def is_v1(self) -> bool: ...
+    def is_v2(self) -> bool: ...
+    def as_v1(self) -> Optional[BackendV1Options]: ...
+    def as_v2(self) -> Optional[BackendV2Options]: ...
+    def to_v1(self) -> BackendV1Options: ...
+    def to_v2(self) -> BackendV2Options: ...
+    @staticmethod
+    def from_v1(inner: BackendV1Options) -> "TranslationBackend": ...
+    @staticmethod
+    def from_v2(inner: BackendV2Options) -> "TranslationBackend": ...
+
+class BackendV1Options:
+    """
+    Options for the V1 translation backend.
+    """
+
+class BackendV2Options:
+    """
+    Options for the V2 translation backend.
+    """

crates/python/qcs_sdk/qpu/translation.pyi

@@ -1,6 +1,7 @@
 from typing import Dict, Optional, final
 
 from qcs_sdk.client import QCSClient
+from qcs_sdk.grpc.models.translation import TranslationOptions
 
 class GetQuiltCalibrationsError(RuntimeError):
     """An error occured while fetching Quil-T calibrations."""
@@ -88,6 +89,7 @@ def translate(
     num_shots: int,
     quantum_processor_id: str,
     client: Optional[QCSClient] = None,
+    translation_options: Optional[TranslationOptions] = None,
 ) -> TranslationResult:
     """
     Translates a native Quil program into an executable program.
@@ -109,6 +111,7 @@ async def translate_async(
     num_shots: int,
     quantum_processor_id: str,
     client: Optional[QCSClient] = None,
+    translation_options: Optional[TranslationOptions] = None,
 ) -> TranslationResult:
     """
     Translates a native Quil program into an executable program.

crates/python/src/grpc/mod.rs

@@ -1 +1,9 @@
+use rigetti_pyo3::create_init_submodule;
+
 pub mod models;
+
+create_init_submodule! {
+    submodules: [
+        "models": models::init_submodule
+    ],
+}

crates/python/src/grpc/models/mod.rs

@@ -1,2 +1,10 @@
+use rigetti_pyo3::create_init_submodule;
+
 pub mod controller;
 pub mod translation;
+
+create_init_submodule! {
+    submodules: [
+        "translation": translation::init_submodule
+    ],
+}

crates/python/src/grpc/models/translation.rs

@@ -1,18 +1,37 @@
 use qcs_api_client_grpc::services::translation::{
     translation_options::TranslationBackend, BackendV1Options, BackendV2Options, TranslationOptions,
 };
-use rigetti_pyo3::{py_wrap_data_struct, py_wrap_type, py_wrap_union_enum};
+use rigetti_pyo3::{
+    create_init_submodule, py_wrap_data_struct, py_wrap_type, py_wrap_union_enum,
+    pyo3::{pymethods, PyResult},
+};
 
 py_wrap_type! {
     #[derive(Default)]
     PyBackendV1Options(BackendV1Options) as "BackendV1Options";
 }
 
+#[pymethods]
+impl PyBackendV1Options {
+    #[new]
+    fn __new__() -> PyResult<Self> {
+        Ok(Self::default())
+    }
+}
+
 py_wrap_type! {
     #[derive(Default)]
     PyBackendV2Options(BackendV2Options) as "BackendV2Options";
 }
 
+#[pymethods]
+impl PyBackendV2Options {
+    #[new]
+    fn __new__() -> PyResult<Self> {
+        Ok(Self::default())
+    }
+}
+
 py_wrap_union_enum! {
     PyTranslationBackend(TranslationBackend) as "TranslationBackend" {
         v1: V1 => PyBackendV1Options,
@@ -26,3 +45,22 @@ py_wrap_data_struct! {
         translation_backend: Option<TranslationBackend> => Option<PyTranslationBackend>
     }
 }
+
+#[pymethods]
+impl PyTranslationOptions {
+    #[new]
+    fn __new__(translation_backend: Option<PyTranslationBackend>) -> PyResult<Self> {
+        Ok(Self(TranslationOptions {
+            translation_backend: translation_backend.map(|b| b.0),
+        }))
+    }
+}
+
+create_init_submodule! {
+    classes: [
+        PyTranslationBackend,
+        PyTranslationOptions,
+        PyBackendV1Options,
+        PyBackendV2Options
+    ],
+}

crates/python/src/lib.rs

@@ -36,6 +36,7 @@ create_init_submodule! {
     submodules: [
         "client": client::init_submodule,
         "compiler": compiler::init_submodule,
+        "grpc": grpc::init_submodule,
         "qpu": qpu::init_submodule,
         "qvm": qvm::init_submodule
     ],