cqlib_core/compile/transform/layout/
result.rs

1// This code is part of Cqlib.
2//
3// (C) Copyright China Telecom Quantum Group 2025-2026
4//
5// This code is licensed under the Apache License, Version 2.0. You may
6// obtain a copy of this license in the LICENSE.txt file in the root directory
7// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8//
9// Any modifications or derivative works of this code must retain this
10// copyright notice, and modified files need to carry a notice indicating
11// that they have been altered from the originals.
12
13//! Result types for concrete layout algorithms.
14//!
15//! Layout algorithms return both the selected mapping and enough metadata for
16//! compiler pipelines to explain why that mapping was chosen. Diagnostics are
17//! intentionally lightweight and human-readable; they are not a stable machine
18//! protocol.
19
20use super::objective::LayoutScore;
21use crate::device::Layout;
22
23/// Candidate or selected layout produced by a concrete layout algorithm.
24///
25/// Most production layout entries return a scored result. The score remains
26/// optional so simple adapters or future algorithms can report a valid layout
27/// before a final objective has been evaluated.
28#[derive(Debug, Clone, PartialEq)]
29pub struct LayoutResult {
30    /// Selected logical-to-physical mapping.
31    pub layout: Layout,
32    /// Optional observed score for this layout under the requested objective.
33    ///
34    /// Individual algorithms may use a different selection key. In
35    /// particular, SABRE selects its winner by predicted route quality under
36    /// the prepared routing cost model and reports this score for diagnostics.
37    pub score: Option<LayoutScore>,
38    /// Diagnostics describing search and scoring behavior.
39    pub diagnostics: LayoutDiagnostics,
40}
41
42/// Diagnostics emitted by layout planning.
43#[derive(Debug, Clone, Default, PartialEq, Eq)]
44pub struct LayoutDiagnostics {
45    /// Whether this layout directly realizes every two-qubit interaction on an
46    /// adjacent hardware edge.
47    pub is_perfect: bool,
48    /// Number of candidate layouts considered by the method.
49    ///
50    /// Algorithms count this according to their own search unit: for example,
51    /// greedy placement counts local placement candidates, while VF2 and SABRE
52    /// count complete layouts that were evaluated.
53    pub candidates_evaluated: usize,
54    /// Whether fidelity/error data contributed to the selected score.
55    pub used_fidelity: bool,
56    /// Human-readable notes for debug reports and compiler logs.
57    pub notes: Vec<String>,
58}
59
60impl LayoutDiagnostics {
61    /// Creates empty diagnostics.
62    pub fn new() -> Self {
63        Self::default()
64    }
65
66    /// Adds one diagnostic note and returns the updated diagnostics.
67    pub fn with_note(mut self, note: impl Into<String>) -> Self {
68        self.notes.push(note.into());
69        self
70    }
71}
cqlib_core/compile/transform/layout/result.rs

cqlib_core/compile/transform/layout/
result.rs
