Module layout 

Initial-layout algorithms for quantum compilation.

A layout maps each logical circuit qubit to one usable physical qubit on a target device. This module only chooses that initial mapping. It does not insert SWAP operations, rewrite instructions, or produce a fully routed physical circuit; routing is handled by later compiler stages such as the SABRE routing core.

The shared pipeline is:

1. analyze_circuit_for_layout extracts weighted logical interactions from a Circuit.
2. PhysicalLayoutGraph::from_device turns a Device into a compiler-local physical topology and calibration view.
3. A concrete algorithm, such as trivial_layout, greedy_layout, vf2_perfect_layout, or sabre_layout, returns a LayoutResult.

Mixed quantum/classical circuits are analyzed structurally. Layout analysis recursively visits if, while, for, and switch bodies so interactions hidden behind classical control still influence the initial mapping. It does not estimate branch probabilities, loop trip counts, or runtime paths.

Examples

use cqlib_core::circuit::{Circuit, Qubit};
use cqlib_core::compile::transform::{LayoutObjective, trivial_layout};
use cqlib_core::device::Device;

let mut circuit = Circuit::new(2);
circuit.cx(Qubit::new(0), Qubit::new(1)).unwrap();
let device = Device::line("line-2", 2).unwrap();

let result = trivial_layout(&circuit, &device, &LayoutObjective::topology_only()).unwrap();
assert!(result.score.is_some());

Re-exports

pub use crate::compile::physical_target::DistanceTable;

pub use crate::compile::physical_target::PhysicalLayoutGraph;

Structs

CircuitLayoutAnalysis

Layout-relevant summary of a circuit.

Interaction

One weighted logical interaction between two logical qubits.

InteractionGraph

Weighted logical interaction graph.

LayoutDiagnostics

Diagnostics emitted by layout planning.

LayoutObjective

Weighted scoring objective used to rank candidate layouts.

LayoutResult

Candidate or selected layout produced by a concrete layout algorithm.

LayoutScore

Breakdown of one layout score.

PreparedSabreCircuit

Circuit-side data prepared once for repeated SABRE layout selection.

PreparedSabreTarget

Device-side SABRE data prepared for one circuit’s interaction signatures.

Vf2LayoutConfig

Configuration for vf2_perfect_layout.

Enums

Vf2EdgeRequirement

Selects which logical interaction edges must be matched by VF2.

Functions

analyze_circuit_for_layout

Extracts layout-relevant interaction data from a circuit.

greedy_layout

Builds a deterministic greedy initial layout from weighted interactions.

greedy_layout_prepared

Builds a deterministic greedy layout from an already-built physical graph.

prepare_sabre_circuit

Prepares the circuit-side analysis and dependency models used by SABRE.

prepare_sabre_device_target

Prepares exact device-native SABRE data for a circuit.

prepare_sabre_topology_target

Prepares topology-only SABRE data for a circuit.

sabre_layout

Selects an initial layout with fused SABRE refinement and routing search.

sabre_layout_prepared

Selects a SABRE initial layout from prepared circuit-side data.

trivial_layout

Maps logical qubits to usable physical qubits in their existing order.

trivial_layout_prepared

Maps logical qubits to a prepared physical graph in their existing order.

vf2_perfect_layout

Searches for a perfect initial layout using non-induced VF2++ matching.

vf2_perfect_layout_prepared

Searches for a perfect initial layout on an already-built physical graph.