[WIP] Prototype backend v3 interface

Author: mtreinish

Cargo.lock

@@ -20,6 +20,7 @@ qiskit-quantum-info.workspace = true
 qiskit-circuit.workspace = true
 qiskit-circuit-library.workspace = true
 qiskit-transpiler.workspace = true
+qiskit-providers.workspace = true
 pyo3 = { workspace = true, optional = true }
 indexmap.workspace = true
 ahash.workspace = true

crates/cext/Cargo.toml

@@ -0,0 +1,181 @@
+// This code is part of Qiskit.
+//
+// (C) Copyright IBM 2026
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE.txt file in the root directory
+// of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+use crate::pointers::{const_ptr_as_ref, mut_ptr_as_ref};
+use qiskit_providers::{BackendV3, ExecutionResult, JobV2, QuantumProgram};
+use qiskit_transpiler::target::Target;
+use std::convert::Infallible;
+use std::ffi::{CStr, c_char, c_void};
+
+pub struct CJobInterface {
+    context: *mut c_void,
+    job_id: Option<unsafe extern "C" fn(context: *mut c_void) -> *const c_char>,
+    status: Option<unsafe extern "C" fn(context: *mut c_void) -> *const c_char>,
+    cancel: Option<unsafe extern "C" fn(context: *mut c_void)>,
+    result: Option<unsafe extern "C" fn(context: *mut c_void) -> *const ExecutionResult>,
+}
+
+pub struct CBackendInterface {
+    context: *mut c_void,
+    //    init: Option<unsafe extern "C" fn(context: *mut c_void)>,
+    name: Option<unsafe extern "C" fn(context: *mut c_void) -> *const c_char>,
+    description: Option<unsafe extern "C" fn(context: *mut c_void) -> *const c_char>,
+    target: Option<unsafe extern "C" fn(context: *mut c_void) -> *const Target>,
+    execute_fn: Option<
+        unsafe extern "C" fn(
+            context: *mut c_void,
+            program: *const QuantumProgram,
+        ) -> *mut CJobInterface,
+    >,
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn qk_backend_new(context: *mut c_void) -> *mut CBackendInterface {
+    Box::into_raw(Box::new(CBackendInterface {
+        context,
+        name: None,
+        description: None,
+        target: None,
+        execute_fn: None,
+    }))
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn qk_backend_set_target(
+    backend: *mut CBackendInterface,
+    fn_ptr: unsafe extern "C" fn(context: *mut c_void) -> *const Target,
+) {
+    let backend = unsafe { mut_ptr_as_ref(backend) };
+    backend.target = Some(fn_ptr);
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn qk_backend_set_name(
+    backend: *mut CBackendInterface,
+    fn_ptr: unsafe extern "C" fn(context: *mut c_void) -> *const c_char,
+) {
+    let backend = unsafe { mut_ptr_as_ref(backend) };
+    backend.name = Some(fn_ptr);
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn qk_backend_set_description(
+    backend: *mut CBackendInterface,
+    fn_ptr: unsafe extern "C" fn(context: *mut c_void) -> *const c_char,
+) {
+    let backend = unsafe { mut_ptr_as_ref(backend) };
+    backend.description = Some(fn_ptr);
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn qk_backend_set_execute(
+    backend: *mut CBackendInterface,
+    fn_ptr: unsafe extern "C" fn(
+        context: *mut c_void,
+        program: *const QuantumProgram,
+    ) -> *mut CJobInterface,
+) {
+    let backend = unsafe { mut_ptr_as_ref(backend) };
+    backend.execute_fn = Some(fn_ptr);
+}
+
+impl BackendV3 for CBackendInterface {
+    type Error = Infallible;
+
+    fn name(&self) -> Option<&str> {
+        self.name.and_then(|callback| {
+            let result = unsafe { callback(self.context) };
+            if result.is_null() {
+                None
+            } else {
+                Some(unsafe { CStr::from_ptr(result) }.to_str().unwrap())
+            }
+        })
+    }
+
+    fn description(&self) -> Option<&str> {
+        self.description.and_then(|callback| {
+            let result = unsafe { callback(self.context) };
+            if result.is_null() {
+                None
+            } else {
+                Some(unsafe { CStr::from_ptr(result) }.to_str().unwrap())
+            }
+        })
+    }
+
+    fn target(&mut self) -> Result<&Target, Infallible> {
+        let Some(callback) = self.target else {
+            panic!(
+                "target not set for backend interface, qk_backend_set_target must be set before using the backend"
+            );
+        };
+        let target_ptr = unsafe { callback(self.context) };
+
+        Ok(unsafe { const_ptr_as_ref(target_ptr) })
+    }
+
+    fn execute(&self, program: &QuantumProgram) -> impl JobV2<Error = Infallible> {
+        let Some(callback) = self.execute_fn else {
+            panic!(
+                "execute function not set for backend interface. qk_backend_set_execute must be set before using the backend"
+            );
+        };
+        let job_ptr = unsafe { callback(self.context, program) };
+        unsafe { mut_ptr_as_ref(job_ptr) }
+    }
+}
+
+impl JobV2 for &mut CJobInterface {
+    type Error = Infallible;
+    fn job_id(&self) -> &str {
+        let Some(callback) = self.job_id else {
+            panic!(
+                "job id function not set for job interface. qk_job_set_job_id must be set before using this job"
+            );
+        };
+        let result = unsafe { callback(self.context) };
+        unsafe { CStr::from_ptr(result) }.to_str().unwrap()
+    }
+
+    fn status(&self) -> String {
+        let Some(callback) = self.status else {
+            panic!(
+                "status function not set for job interface. qk_job_set_job_status must be set before using this job"
+            );
+        };
+        let result = unsafe { callback(self.context) };
+        unsafe { CStr::from_ptr(result) }
+            .to_str()
+            .unwrap()
+            .to_owned()
+    }
+
+    fn cancel(&self) {
+        let Some(callback) = self.cancel else {
+            panic!(
+                "cancel function not set for job interface. qk_job_set_job_cancel must be set before using this job"
+            );
+        };
+        unsafe { callback(self.context) };
+    }
+
+    fn result(&self) -> Result<ExecutionResult, Infallible> {
+        let Some(callback) = self.result else {
+            panic!(
+                "result function not set for job interface. qk_job_set_job_cancel must be set before using this job"
+            );
+        };
+        let result = unsafe { const_ptr_as_ref(callback(self.context)) };
+        Ok(result.clone())
+    }
+}

crates/cext/src/backend.rs

@@ -15,6 +15,7 @@ mod pointers;
 #[cfg(feature = "python_binding")]
 mod py;
 
+pub mod backend;
 pub mod circuit;
 pub mod circuit_library;
 pub mod dag;

crates/cext/src/lib.rs

@@ -9,6 +9,7 @@ license.workspace = true
 name = "qiskit_providers"
 
 [dependencies]
+qiskit-transpiler.workspace = true
 
 [dependencies.hashbrown]
 workspace = true

crates/providers/Cargo.toml

@@ -0,0 +1,47 @@
+// This code is part of Qiskit.
+//
+// (C) Copyright IBM 2026
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE.txt file in the root directory
+// of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+use qiskit_transpiler::target::Target;
+
+#[derive(Clone)]
+pub struct QuantumProgram {
+    pub placeholder: Vec<u8>,
+}
+
+#[derive(Clone)]
+pub struct ExecutionResult {
+    pub placeholder: Vec<u32>,
+}
+
+/// This is the trait defining the interface for job objects in the backend interface
+pub trait JobV2 {
+    type Error;
+
+    fn job_id(&self) -> &str;
+    fn result(&self) -> Result<ExecutionResult, Self::Error>;
+    fn cancel(&self);
+    fn status(&self) -> String;
+}
+
+/// This trait defines the common backend
+pub trait BackendV3 {
+    type Error;
+
+    /// An optional name for this backend instance
+    fn name(&self) -> Option<&str>;
+    /// An optional description for this backend instance
+    fn description(&self) -> Option<&str>;
+    /// The target describing the QPU constraints for executing circuits
+    fn target(&mut self) -> Result<&Target, Self::Error>;
+    /// The execution
+    fn execute(&self, program: &QuantumProgram) -> impl JobV2<Error = Self::Error>;
+}

crates/providers/src/backend_v3.rs

@@ -10,6 +10,8 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
+mod backend_v3;
 mod data_tree;
 
+pub use backend_v3::{BackendV3, ExecutionResult, JobV2, QuantumProgram};
 pub use data_tree::{DataTree, PathEntry};

crates/providers/src/lib.rs

@@ -41,3 +41,5 @@ qiskit-cext-vtable = { workspace = true, features = ["python_binding", "addr"] }
 qiskit-transpiler.workspace = true
 qiskit-quantum-info.workspace = true
 qiskit-synthesis.workspace = true
+qiskit-providers.workspace = true
+qiskit-util.workspace = true

crates/pyext/Cargo.toml

@@ -14,6 +14,7 @@ use pyo3::prelude::*;
 pub use qiskit_cext::*;
 
 mod capi;
+mod providers;
 
 #[inline(always)]
 #[doc(hidden)]
@@ -98,7 +99,7 @@ fn _accelerate(m: &Bound<PyModule>) -> PyResult<()> {
     add_submodule(m, ::qiskit_transpiler::passes::optimize_clifford_t_mod, "optimize_clifford_t")?;
     add_submodule(m, ::qiskit_transpiler::passes::substitute_pi4_rotations_mod, "substitute_pi4_rotations")?;
     add_submodule(m, ::qiskit_transpiler::passes::synthesize_rz_rotations_mod, "synthesize_rz_rotations")?;
-
     add_submodule(m, ::qiskit_transpiler::passes::convert_to_pauli_rotations_mod, "convert_to_pauli_rotations")?;
+    add_submodule(m, providers::providers, "providers")?;
     Ok(())
 }