Skip to main content

qualia_core_db/solvers/qpu/
dispatcher.rs

1//! In-process QPU job queue and dispatcher.
2//!
3//! This module manages the lifecycle of QPU jobs in memory.  Actual HTTP
4//! egress to the 8 supported providers (IBM, D-Wave, IonQ, Rigetti, Azure,
5//! Braket, Google, Quantinuum) is handled by `qualia-client-core::qpu_dispatcher`.
6//!
7//! Ported from `qpu/src/dispatcher.rs`.
8
9use super::{JobStatus, QpuError, QpuJob, QpuResult};
10use std::cmp::Ordering;
11use std::collections::{BinaryHeap, HashMap};
12use std::sync::Arc;
13use tokio::sync::{Mutex, RwLock};
14
15// ── Job state ─────────────────────────────────────────────────────────────────
16
17#[derive(Debug, Clone)]
18struct JobState {
19    job: QpuJob,
20    enqueued_at_ms: u64,
21    retries: u32,
22    status: InternalStatus,
23}
24
25#[derive(Debug, Clone, PartialEq)]
26enum InternalStatus {
27    Queued,
28    Submitted,
29    Running,
30    Completed,
31    Failed,
32}
33
34fn now_ms() -> u64 {
35    std::time::SystemTime::now()
36        .duration_since(std::time::UNIX_EPOCH)
37        .map(|d| d.as_millis() as u64)
38        .unwrap_or(0)
39}
40
41// ── Queue statistics ──────────────────────────────────────────────────────────
42
43#[derive(Debug, Clone)]
44pub struct QueueStats {
45    pub pending_count: usize,
46    pub running_count: usize,
47    pub completed_count: usize,
48}
49
50// ── Job queue ─────────────────────────────────────────────────────────────────
51
52/// Prioritized job wrapper for QGroup heuristic
53#[derive(Debug, Clone)]
54pub struct PrioritizedJob(pub QpuJob);
55
56impl PartialEq for PrioritizedJob {
57    fn eq(&self, other: &Self) -> bool {
58        self.0.job_id == other.0.job_id
59    }
60}
61impl Eq for PrioritizedJob {}
62
63impl PartialOrd for PrioritizedJob {
64    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
65        Some(self.cmp(other))
66    }
67}
68
69impl Ord for PrioritizedJob {
70    fn cmp(&self, other: &Self) -> Ordering {
71        // QGroup heuristic: group by similar circuit depth and shot count.
72        // We sort descending so the BinaryHeap (max-heap) pops highest depth first,
73        // and jobs with similar depths will be contiguous.
74        let depth_ord = self
75            .0
76            .parameters
77            .circuit_depth
78            .cmp(&other.0.parameters.circuit_depth);
79        if depth_ord != Ordering::Equal {
80            return depth_ord;
81        }
82        self.0.parameters.shots.cmp(&other.0.parameters.shots)
83    }
84}
85
86/// In-process job queue.  HTTP dispatch is performed by the caller via
87/// `submit_fn` passed to `process_queue`.
88pub struct JobQueue {
89    pending: Arc<Mutex<BinaryHeap<PrioritizedJob>>>,
90    running: Arc<RwLock<HashMap<String, JobState>>>,
91    completed: Arc<Mutex<Vec<QpuResult>>>,
92}
93
94impl JobQueue {
95    /// Creates a default `JobQueue`.
96    pub fn new() -> Self {
97        Self {
98            pending: Arc::new(Mutex::new(BinaryHeap::new())),
99            running: Arc::new(RwLock::new(HashMap::new())),
100            completed: Arc::new(Mutex::new(Vec::new())),
101        }
102    }
103
104    /// Enqueue a job for dispatch.
105    pub async fn enqueue(&self, job: QpuJob) -> String {
106        let id = job.job_id.clone();
107        self.pending.lock().await.push(PrioritizedJob(job));
108        id
109    }
110
111    /// Drain the pending queue and call `dispatch` for each job.
112    ///
113    /// `dispatch` should return the provider-assigned job ID on success.
114    pub async fn process_queue<F>(&self, dispatch: F) -> Result<(), QpuError>
115    where
116        F: Fn(&QpuJob) -> Result<String, String>,
117    {
118        let jobs: Vec<QpuJob> = {
119            let mut pending = self.pending.lock().await;
120            let mut jobs = Vec::with_capacity(pending.len());
121            while let Some(job) = pending.pop() {
122                jobs.push(job.0);
123            }
124            jobs
125        };
126
127        for job in jobs {
128            let job_id = job.job_id.clone();
129
130            let mut state = JobState {
131                job: job.clone(),
132                enqueued_at_ms: now_ms(),
133                retries: 0,
134                status: InternalStatus::Queued,
135            };
136
137            let mut dispatch_result = dispatch(&job);
138
139            while dispatch_result.is_err() && state.retries < 3 {
140                state.retries += 1;
141                log::warn!(
142                    "Retrying QPU dispatch for {} (retry {})",
143                    job_id,
144                    state.retries
145                );
146                dispatch_result = dispatch(&job);
147            }
148
149            match dispatch_result {
150                Ok(provider_id) => {
151                    state.job.job_id = provider_id.clone();
152                    state.status = InternalStatus::Submitted;
153                    self.running
154                        .write()
155                        .await
156                        .insert(provider_id.clone(), state.clone());
157
158                    let mut running = self.running.write().await;
159                    if let Some(s) = running.get_mut(&provider_id) {
160                        s.status = InternalStatus::Running;
161                    }
162                }
163                Err(e) => {
164                    log::error!(
165                        "QPU dispatch failed for {} after {} retries: {}",
166                        job_id,
167                        state.retries,
168                        e
169                    );
170                    state.status = InternalStatus::Failed;
171                    let result = QpuResult::failed(job_id, e);
172                    self.completed.lock().await.push(result);
173                }
174            }
175        }
176        Ok(())
177    }
178
179    /// Mark a running job as completed or failed based on a polled status.
180    pub async fn record_result(&self, job_id: &str, result: QpuResult) {
181        let mut running = self.running.write().await;
182        if let Some(mut state) = running.remove(job_id) {
183            state.status = if result.error.is_some() {
184                InternalStatus::Failed
185            } else {
186                InternalStatus::Completed
187            };
188            let _duration = now_ms() - state.enqueued_at_ms;
189        }
190        self.completed.lock().await.push(result);
191    }
192
193    /// Drain and return all completed results.
194    pub async fn take_results(&self) -> Vec<QpuResult> {
195        std::mem::take(&mut *self.completed.lock().await)
196    }
197
198    /// Queue stats.
199    pub async fn stats(&self) -> QueueStats {
200        QueueStats {
201            pending_count: self.pending.lock().await.len(),
202            running_count: self.running.read().await.len(),
203            completed_count: self.completed.lock().await.len(),
204        }
205    }
206}
207
208impl Default for JobQueue {
209    fn default() -> Self {
210        Self::new()
211    }
212}
213
214// ── Dispatcher ────────────────────────────────────────────────────────────────
215
216/// Wraps a `JobQueue` and exposes a simple submit/poll API.
217pub struct Dispatcher {
218    pub queue: Arc<JobQueue>,
219}
220
221impl Dispatcher {
222    /// Creates a default `Dispatcher`.
223    pub fn new() -> Self {
224        Self {
225            queue: Arc::new(JobQueue::new()),
226        }
227    }
228
229    /// Submits a job; returns its id.
230    pub async fn submit(&self, job: QpuJob) -> String {
231        self.queue.enqueue(job).await
232    }
233
234    /// Flushes queued jobs through `dispatch`.
235    pub async fn flush<F>(&self, dispatch: F) -> Result<(), QpuError>
236    where
237        F: Fn(&QpuJob) -> Result<String, String>,
238    {
239        self.queue.process_queue(dispatch).await
240    }
241
242    /// Drains completed results.
243    pub async fn drain_results(&self) -> Vec<QpuResult> {
244        self.queue.take_results().await
245    }
246
247    /// Queue stats.
248    pub async fn stats(&self) -> QueueStats {
249        self.queue.stats().await
250    }
251}
252
253impl Default for Dispatcher {
254    fn default() -> Self {
255        Self::new()
256    }
257}
258
259// ── Fallback handler ──────────────────────────────────────────────────────────
260
261/// Returns a classical-simulation result when no QPU provider is available.
262pub struct FallbackHandler {
263    pub enabled: bool,
264}
265
266impl FallbackHandler {
267    /// Creates a default `FallbackHandler`.
268    pub fn new(enabled: bool) -> Self {
269        Self { enabled }
270    }
271
272    /// Classical fallback for a job.
273    pub fn simulate_classically(&self, job: &QpuJob) -> Result<QpuResult, QpuError> {
274        if !self.enabled {
275            return Err(QpuError::Api("Fallback is disabled".into()));
276        }
277        Ok(QpuResult {
278            job_id: job.job_id.clone(),
279            status: JobStatus::Completed,
280            result: Some(super::JobResultData {
281                measurements: vec![],
282                energies: Some(vec![0.0]),
283                metadata: serde_json::json!({"method": "classical_simulation"}),
284            }),
285            completed_at_ms: Some(
286                std::time::SystemTime::now()
287                    .duration_since(std::time::UNIX_EPOCH)
288                    .map(|d| d.as_millis() as u64)
289                    .unwrap_or(0),
290            ),
291            error: None,
292        })
293    }
294}
295
296#[cfg(test)]
297mod tests {
298    use super::*;
299    use crate::solvers::qpu::{JobParameters, ProblemType};
300
301    #[tokio::test]
302    async fn queue_enqueue_and_stats() {
303        let q = JobQueue::new();
304        let job = QpuJob::new(
305            "test-job-1".into(),
306            ProblemType::Annealing,
307            JobParameters::default(),
308        );
309        q.enqueue(job).await;
310        let stats = q.stats().await;
311        assert_eq!(stats.pending_count, 1);
312    }
313
314    #[test]
315    fn fallback_handler_enabled() {
316        let handler = FallbackHandler::new(true);
317        let job = QpuJob::default();
318        let result = handler.simulate_classically(&job).unwrap();
319        assert_eq!(result.status, JobStatus::Completed);
320    }
321
322    #[test]
323    fn fallback_handler_disabled() {
324        let handler = FallbackHandler::new(false);
325        let job = QpuJob::default();
326        assert!(handler.simulate_classically(&job).is_err());
327    }
328
329    #[tokio::test]
330    async fn test_qgroup_heuristic_sorting() {
331        let q = JobQueue::new();
332
333        let mut job1 = QpuJob::new("job1".into(), ProblemType::Vqe, JobParameters::default());
334        job1.parameters.circuit_depth = 10;
335        job1.parameters.shots = 1000;
336
337        let mut job2 = QpuJob::new("job2".into(), ProblemType::Vqe, JobParameters::default());
338        job2.parameters.circuit_depth = 50;
339        job2.parameters.shots = 1000;
340
341        let mut job3 = QpuJob::new("job3".into(), ProblemType::Vqe, JobParameters::default());
342        job3.parameters.circuit_depth = 10;
343        job3.parameters.shots = 2000;
344
345        let mut job4 = QpuJob::new("job4".into(), ProblemType::Vqe, JobParameters::default());
346        job4.parameters.circuit_depth = 50;
347        job4.parameters.shots = 500;
348
349        // Enqueue jobs in random order
350        q.enqueue(job1).await;
351        q.enqueue(job2).await;
352        q.enqueue(job3).await;
353        q.enqueue(job4).await;
354
355        let jobs = {
356            let mut pending = q.pending.lock().await;
357            let mut extracted = Vec::new();
358            while let Some(job) = pending.pop() {
359                extracted.push(job.0);
360            }
361            extracted
362        };
363
364        // BinaryHeap pops the largest first.
365        // Based on our Ord implementation: highest depth first, then highest shots.
366        assert_eq!(jobs[0].job_id, "job2"); // depth: 50, shots: 1000
367        assert_eq!(jobs[1].job_id, "job4"); // depth: 50, shots: 500
368        assert_eq!(jobs[2].job_id, "job3"); // depth: 10, shots: 2000
369        assert_eq!(jobs[3].job_id, "job1"); // depth: 10, shots: 1000
370    }
371}