quantrs2_sim/fpga_acceleration/

types.rs

//! Auto-generated module
//!
//! 🤖 Generated with [SplitRS](https://github.com/cool-japan/splitrs)

use crate::circuit_interfaces::{InterfaceCircuit, InterfaceGate, InterfaceGateType};
use crate::error::{Result, SimulatorError};
use scirs2_core::ndarray::Array1;
use scirs2_core::Complex64;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Bitstream management
#[derive(Debug, Clone)]
pub struct BitstreamManager {
    /// Available bitstreams
    pub bitstreams: HashMap<String, Bitstream>,
    /// Current configuration
    pub current_config: Option<String>,
    /// Reconfiguration time (ms)
    pub reconfig_time_ms: f64,
    /// Partial reconfiguration support
    pub supports_partial_reconfig: bool,
}
/// Pipeline stage
#[derive(Debug, Clone)]
pub struct PipelineStage {
    /// Stage name
    pub name: String,
    /// Stage operation
    pub operation: PipelineOperation,
    /// Latency (clock cycles)
    pub latency: usize,
    /// Throughput (operations per cycle)
    pub throughput: f64,
}
/// Memory access patterns
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemoryAccessPattern {
    Sequential,
    Random,
    Strided,
    BlockTransfer,
    Streaming,
}
/// Timing information
#[derive(Debug, Clone, Default)]
pub struct TimingInfo {
    /// Critical path delay (ns)
    pub critical_path_delay: f64,
    /// Setup slack (ns)
    pub setup_slack: f64,
    /// Hold slack (ns)
    pub hold_slack: f64,
    /// Maximum frequency (MHz)
    pub max_frequency: f64,
}
/// Memory interface types
#[derive(Debug, Clone)]
pub struct MemoryInterface {
    /// Interface type
    pub interface_type: MemoryInterfaceType,
    /// Bandwidth (GB/s)
    pub bandwidth: f64,
    /// Capacity (GB)
    pub capacity: f64,
    /// Latency (ns)
    pub latency: f64,
}
/// FPGA platform types
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FPGAPlatform {
    /// Intel Arria 10
    IntelArria10,
    /// Intel Stratix 10
    IntelStratix10,
    /// Intel Agilex 7
    IntelAgilex7,
    /// Xilinx Virtex `UltraScale`+
    XilinxVirtexUltraScale,
    /// Xilinx Versal ACAP
    XilinxVersal,
    /// Xilinx Kintex `UltraScale`+
    XilinxKintexUltraScale,
    /// Simulation mode
    Simulation,
}
/// FPGA device information
#[derive(Debug, Clone)]
pub struct FPGADeviceInfo {
    /// Device ID
    pub device_id: usize,
    /// Platform type
    pub platform: FPGAPlatform,
    /// Logic elements/LUTs
    pub logic_elements: usize,
    /// DSP blocks
    pub dsp_blocks: usize,
    /// Block RAM (KB)
    pub block_ram_kb: usize,
    /// Clock frequency (MHz)
    pub max_clock_frequency: f64,
    /// Memory interfaces
    pub memory_interfaces: Vec<MemoryInterface>,
    /// `PCIe` lanes
    pub pcie_lanes: usize,
    /// Power consumption (W)
    pub power_consumption: f64,
    /// Supported arithmetic precision
    pub supported_precision: Vec<ArithmeticPrecision>,
}
impl FPGADeviceInfo {
    /// Return the published reference specifications for an FPGA platform.
    ///
    /// IMPORTANT: this is a static *reference spec table* (datasheet figures
    /// such as logic-element / DSP-block counts), NOT a hardware-detection
    /// result. It does not probe a `PCIe` bus or assert that any board is
    /// present. Only [`FPGAPlatform::Simulation`] corresponds to something this
    /// build can run: a CPU-side numerical simulation of the gate math (see
    /// [`FPGAQuantumSimulator::new`]). The real-board rows exist purely as
    /// reference data for callers that have such hardware elsewhere.
    #[must_use]
    pub fn for_platform(platform: FPGAPlatform) -> Self {
        match platform {
            FPGAPlatform::IntelArria10 => Self {
                device_id: 1,
                platform,
                logic_elements: 1_150_000,
                dsp_blocks: 1688,
                block_ram_kb: 53_000,
                max_clock_frequency: 400.0,
                memory_interfaces: vec![MemoryInterface {
                    interface_type: MemoryInterfaceType::DDR4,
                    bandwidth: 34.0,
                    capacity: 32.0,
                    latency: 200.0,
                }],
                pcie_lanes: 16,
                power_consumption: 100.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float32,
                ],
            },
            FPGAPlatform::IntelStratix10 => Self {
                device_id: 2,
                platform,
                logic_elements: 2_800_000,
                dsp_blocks: 5760,
                block_ram_kb: 229_000,
                max_clock_frequency: 500.0,
                memory_interfaces: vec![
                    MemoryInterface {
                        interface_type: MemoryInterfaceType::DDR4,
                        bandwidth: 68.0,
                        capacity: 64.0,
                        latency: 180.0,
                    },
                    MemoryInterface {
                        interface_type: MemoryInterfaceType::HBM2,
                        bandwidth: 460.0,
                        capacity: 8.0,
                        latency: 50.0,
                    },
                ],
                pcie_lanes: 16,
                power_consumption: 150.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float32,
                    ArithmeticPrecision::Float64,
                ],
            },
            FPGAPlatform::IntelAgilex7 => Self {
                device_id: 3,
                platform,
                logic_elements: 2_500_000,
                dsp_blocks: 4608,
                block_ram_kb: 180_000,
                max_clock_frequency: 600.0,
                memory_interfaces: vec![
                    MemoryInterface {
                        interface_type: MemoryInterfaceType::DDR5,
                        bandwidth: 102.0,
                        capacity: 128.0,
                        latency: 150.0,
                    },
                    MemoryInterface {
                        interface_type: MemoryInterfaceType::HBM3,
                        bandwidth: 819.0,
                        capacity: 16.0,
                        latency: 40.0,
                    },
                ],
                pcie_lanes: 32,
                power_consumption: 120.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float16,
                    ArithmeticPrecision::Float32,
                    ArithmeticPrecision::Float64,
                ],
            },
            FPGAPlatform::XilinxVirtexUltraScale => Self {
                device_id: 4,
                platform,
                logic_elements: 1_300_000,
                dsp_blocks: 6840,
                block_ram_kb: 75_900,
                max_clock_frequency: 450.0,
                memory_interfaces: vec![MemoryInterface {
                    interface_type: MemoryInterfaceType::DDR4,
                    bandwidth: 77.0,
                    capacity: 64.0,
                    latency: 190.0,
                }],
                pcie_lanes: 16,
                power_consumption: 130.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float32,
                ],
            },
            FPGAPlatform::XilinxVersal => Self {
                device_id: 5,
                platform,
                logic_elements: 1_968_000,
                dsp_blocks: 9024,
                block_ram_kb: 175_000,
                max_clock_frequency: 700.0,
                memory_interfaces: vec![
                    MemoryInterface {
                        interface_type: MemoryInterfaceType::DDR5,
                        bandwidth: 120.0,
                        capacity: 256.0,
                        latency: 140.0,
                    },
                    MemoryInterface {
                        interface_type: MemoryInterfaceType::HBM3,
                        bandwidth: 1024.0,
                        capacity: 32.0,
                        latency: 35.0,
                    },
                ],
                pcie_lanes: 32,
                power_consumption: 100.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed8,
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float16,
                    ArithmeticPrecision::Float32,
                    ArithmeticPrecision::Float64,
                ],
            },
            FPGAPlatform::XilinxKintexUltraScale => Self {
                device_id: 6,
                platform,
                logic_elements: 850_000,
                dsp_blocks: 2928,
                block_ram_kb: 75_900,
                max_clock_frequency: 500.0,
                memory_interfaces: vec![MemoryInterface {
                    interface_type: MemoryInterfaceType::DDR4,
                    bandwidth: 60.0,
                    capacity: 32.0,
                    latency: 200.0,
                }],
                pcie_lanes: 8,
                power_consumption: 80.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float32,
                ],
            },
            FPGAPlatform::Simulation => Self {
                device_id: 99,
                platform,
                logic_elements: 10_000_000,
                dsp_blocks: 10_000,
                block_ram_kb: 1_000_000,
                max_clock_frequency: 1000.0,
                memory_interfaces: vec![MemoryInterface {
                    interface_type: MemoryInterfaceType::HBM3,
                    bandwidth: 2000.0,
                    capacity: 128.0,
                    latency: 10.0,
                }],
                pcie_lanes: 64,
                power_consumption: 50.0,
                supported_precision: vec![
                    ArithmeticPrecision::Fixed8,
                    ArithmeticPrecision::Fixed16,
                    ArithmeticPrecision::Fixed32,
                    ArithmeticPrecision::Float16,
                    ArithmeticPrecision::Float32,
                    ArithmeticPrecision::Float64,
                ],
            },
        }
    }
}
/// Memory pool
#[derive(Debug, Clone)]
pub struct MemoryPool {
    /// Pool name
    pub name: String,
    /// Size (KB)
    pub size_kb: usize,
    /// Used size (KB)
    pub used_kb: usize,
    /// Access pattern
    pub access_pattern: MemoryAccessPattern,
    /// Banking configuration
    pub banks: usize,
}
/// Scheduling algorithms
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SchedulingAlgorithm {
    FIFO,
    RoundRobin,
    PriorityBased,
    DeadlineAware,
    BandwidthOptimized,
}
/// Memory access scheduler
#[derive(Debug, Clone)]
pub struct MemoryAccessScheduler {
    /// Scheduling algorithm
    pub algorithm: SchedulingAlgorithm,
    /// Request queue size
    pub queue_size: usize,
    /// Priority levels
    pub priority_levels: usize,
}
/// FPGA quantum processing unit
#[derive(Debug, Clone)]
pub struct QuantumProcessingUnit {
    /// Unit ID
    pub unit_id: usize,
    /// Supported gate types
    pub supported_gates: Vec<InterfaceGateType>,
    /// Pipeline stages
    pub pipeline_stages: Vec<PipelineStage>,
    /// Local memory (KB)
    pub local_memory_kb: usize,
    /// Processing frequency (MHz)
    pub frequency: f64,
    /// Utilization percentage
    pub utilization: f64,
}
/// FPGA quantum simulator
pub struct FPGAQuantumSimulator {
    /// Configuration
    config: FPGAConfig,
    /// Device information
    device_info: FPGADeviceInfo,
    /// Processing units
    processing_units: Vec<QuantumProcessingUnit>,
    /// Generated HDL modules
    pub hdl_modules: HashMap<String, HDLModule>,
    /// Performance statistics
    pub stats: FPGAStats,
    /// Memory manager
    pub memory_manager: FPGAMemoryManager,
    /// Bitstream manager
    pub bitstream_manager: BitstreamManager,
}
impl FPGAQuantumSimulator {
    /// Create a new FPGA quantum simulator.
    ///
    /// HONEST BEHAVIOR: this build links no FPGA runtime / board driver, so NO
    /// physical FPGA is ever programmed or used - regardless of the `platform`
    /// requested. This constructor always builds a CPU-side *numerical
    /// simulation* of the FPGA gate math: the gate applications compute the exact
    /// state-vector linear algebra on the CPU. The `platform` field only selects
    /// which datasheet reference-spec table to model (see
    /// [`FPGADeviceInfo::for_platform`]); it does not detect or claim real
    /// silicon. [`Self::is_fpga_available`] therefore always returns `false`.
    pub fn new(config: FPGAConfig) -> Result<Self> {
        let device_info = FPGADeviceInfo::for_platform(config.platform);
        let processing_units = Self::create_processing_units(&config, &device_info)?;
        let memory_manager = Self::create_memory_manager(&config, &device_info)?;
        let bitstream_manager = Self::create_bitstream_manager(&config)?;
        let mut simulator = Self {
            config,
            device_info,
            processing_units,
            hdl_modules: HashMap::new(),
            stats: FPGAStats::default(),
            memory_manager,
            bitstream_manager,
        };
        simulator.generate_hdl_modules()?;
        simulator.load_default_bitstream()?;
        Ok(simulator)
    }
    /// Create processing units
    pub fn create_processing_units(
        config: &FPGAConfig,
        device_info: &FPGADeviceInfo,
    ) -> Result<Vec<QuantumProcessingUnit>> {
        let mut units = Vec::new();
        for i in 0..config.num_processing_units {
            let pipeline_stages = vec![
                PipelineStage {
                    name: "Fetch".to_string(),
                    operation: PipelineOperation::Fetch,
                    latency: 1,
                    throughput: 1.0,
                },
                PipelineStage {
                    name: "Decode".to_string(),
                    operation: PipelineOperation::Decode,
                    latency: 1,
                    throughput: 1.0,
                },
                PipelineStage {
                    name: "Address".to_string(),
                    operation: PipelineOperation::AddressCalculation,
                    latency: 1,
                    throughput: 1.0,
                },
                PipelineStage {
                    name: "MemRead".to_string(),
                    operation: PipelineOperation::MemoryRead,
                    latency: 2,
                    throughput: 0.5,
                },
                PipelineStage {
                    name: "Execute".to_string(),
                    operation: PipelineOperation::GateExecution,
                    latency: 3,
                    throughput: 1.0,
                },
                PipelineStage {
                    name: "MemWrite".to_string(),
                    operation: PipelineOperation::MemoryWrite,
                    latency: 2,
                    throughput: 0.5,
                },
                PipelineStage {
                    name: "Writeback".to_string(),
                    operation: PipelineOperation::Writeback,
                    latency: 1,
                    throughput: 1.0,
                },
            ];
            let unit = QuantumProcessingUnit {
                unit_id: i,
                supported_gates: vec![
                    InterfaceGateType::Hadamard,
                    InterfaceGateType::PauliX,
                    InterfaceGateType::PauliY,
                    InterfaceGateType::PauliZ,
                    InterfaceGateType::CNOT,
                    InterfaceGateType::CZ,
                    InterfaceGateType::RX(0.0),
                    InterfaceGateType::RY(0.0),
                    InterfaceGateType::RZ(0.0),
                ],
                pipeline_stages,
                local_memory_kb: device_info.block_ram_kb / config.num_processing_units,
                frequency: config.clock_frequency,
                utilization: 0.0,
            };
            units.push(unit);
        }
        Ok(units)
    }
    /// Create memory manager
    fn create_memory_manager(
        config: &FPGAConfig,
        device_info: &FPGADeviceInfo,
    ) -> Result<FPGAMemoryManager> {
        let mut onchip_pools = HashMap::new();
        onchip_pools.insert(
            "state_vector".to_string(),
            MemoryPool {
                name: "state_vector".to_string(),
                size_kb: device_info.block_ram_kb / 2,
                used_kb: 0,
                access_pattern: MemoryAccessPattern::Sequential,
                banks: 16,
            },
        );
        onchip_pools.insert(
            "gate_cache".to_string(),
            MemoryPool {
                name: "gate_cache".to_string(),
                size_kb: device_info.block_ram_kb / 4,
                used_kb: 0,
                access_pattern: MemoryAccessPattern::Random,
                banks: 8,
            },
        );
        onchip_pools.insert(
            "instruction_cache".to_string(),
            MemoryPool {
                name: "instruction_cache".to_string(),
                size_kb: device_info.block_ram_kb / 8,
                used_kb: 0,
                access_pattern: MemoryAccessPattern::Sequential,
                banks: 4,
            },
        );
        let external_interfaces: Vec<ExternalMemoryInterface> = device_info
            .memory_interfaces
            .iter()
            .enumerate()
            .map(|(i, _)| ExternalMemoryInterface {
                interface_id: i,
                interface_type: device_info.memory_interfaces[i].interface_type,
                controller: format!("mem_ctrl_{i}"),
                utilization: 0.0,
            })
            .collect();
        let access_scheduler = MemoryAccessScheduler {
            algorithm: SchedulingAlgorithm::BandwidthOptimized,
            queue_size: 64,
            priority_levels: 4,
        };
        Ok(FPGAMemoryManager {
            onchip_pools,
            external_interfaces,
            access_scheduler,
            total_memory_kb: device_info.block_ram_kb,
            used_memory_kb: 0,
        })
    }
    /// Create bitstream manager
    fn create_bitstream_manager(config: &FPGAConfig) -> Result<BitstreamManager> {
        let mut bitstreams = HashMap::new();
        bitstreams.insert(
            "quantum_basic".to_string(),
            Bitstream {
                name: "quantum_basic".to_string(),
                target_config: "Basic quantum gates".to_string(),
                size_kb: 50_000,
                config_time_ms: 200.0,
                supported_algorithms: vec![
                    "VQE".to_string(),
                    "QAOA".to_string(),
                    "Grover".to_string(),
                ],
            },
        );
        bitstreams.insert(
            "quantum_advanced".to_string(),
            Bitstream {
                name: "quantum_advanced".to_string(),
                target_config: "Advanced quantum algorithms".to_string(),
                size_kb: 75_000,
                config_time_ms: 300.0,
                supported_algorithms: vec![
                    "Shor".to_string(),
                    "QFT".to_string(),
                    "Phase_Estimation".to_string(),
                ],
            },
        );
        bitstreams.insert(
            "quantum_ml".to_string(),
            Bitstream {
                name: "quantum_ml".to_string(),
                target_config: "Quantum machine learning".to_string(),
                size_kb: 60_000,
                config_time_ms: 250.0,
                supported_algorithms: vec![
                    "QML".to_string(),
                    "Variational_Circuits".to_string(),
                    "Quantum_GAN".to_string(),
                ],
            },
        );
        Ok(BitstreamManager {
            bitstreams,
            current_config: None,
            reconfig_time_ms: 200.0,
            supports_partial_reconfig: matches!(
                config.platform,
                FPGAPlatform::IntelStratix10
                    | FPGAPlatform::IntelAgilex7
                    | FPGAPlatform::XilinxVersal
            ),
        })
    }
    /// Generate HDL modules for quantum operations
    fn generate_hdl_modules(&mut self) -> Result<()> {
        self.generate_single_qubit_module()?;
        self.generate_two_qubit_module()?;
        self.generate_control_unit_module()?;
        self.generate_memory_controller_module()?;
        self.generate_arithmetic_unit_module()?;
        Ok(())
    }
    /// Generate single qubit gate HDL module.
    ///
    /// Only `SystemVerilog` and `OpenCL` have a complete generator. Other HDL
    /// targets are not implemented and return an honest error rather than a stub
    /// string masquerading as synthesizable HDL.
    fn generate_single_qubit_module(&mut self) -> Result<()> {
        let hdl_code = match self.config.hdl_target {
            HDLTarget::SystemVerilog => self.generate_single_qubit_systemverilog(),
            HDLTarget::OpenCL => self.generate_single_qubit_opencl(),
            other => {
                return Err(SimulatorError::UnsupportedOperation(format!(
                    "FPGA HDL generation: target {other:?} is not implemented \
                     for single_qubit_gate (only SystemVerilog and OpenCL are)"
                )));
            }
        };
        let module = HDLModule {
            name: "single_qubit_gate".to_string(),
            hdl_code,
            resource_utilization: ResourceUtilization {
                luts: 1000,
                flip_flops: 500,
                dsp_blocks: 8,
                bram_kb: 2,
                utilization_percent: 5.0,
            },
            timing_info: TimingInfo {
                critical_path_delay: 3.2,
                setup_slack: 0.8,
                hold_slack: 1.5,
                max_frequency: 312.5,
            },
            module_type: ModuleType::SingleQubitGate,
        };
        self.hdl_modules
            .insert("single_qubit_gate".to_string(), module);
        Ok(())
    }
    /// Generate `SystemVerilog` code for single qubit gates
    fn generate_single_qubit_systemverilog(&self) -> String {
        format!(
            r"
// Single Qubit Gate Processing Unit
// Generated for platform: {:?}
// Clock frequency: {:.1} MHz
// Data path width: {} bits

module single_qubit_gate #(
    parameter DATA_WIDTH = {},
    parameter ADDR_WIDTH = 20,
    parameter PIPELINE_DEPTH = {}
) (
    input  logic                    clk,
    input  logic                    rst_n,
    input  logic                    enable,

    // Gate parameters
    input  logic [1:0]              gate_type,  // 00: H, 01: X, 10: Y, 11: Z
    input  logic [DATA_WIDTH-1:0]   gate_param, // For rotation gates
    input  logic [ADDR_WIDTH-1:0]   target_qubit,

    // State vector interface
    input  logic [DATA_WIDTH-1:0]   state_real_in,
    input  logic [DATA_WIDTH-1:0]   state_imag_in,
    output logic [DATA_WIDTH-1:0]   state_real_out,
    output logic [DATA_WIDTH-1:0]   state_imag_out,

    // Control signals
    output logic                    ready,
    output logic                    valid_out
);

    // Pipeline registers
    logic [DATA_WIDTH-1:0] pipeline_real [0:PIPELINE_DEPTH-1];
    logic [DATA_WIDTH-1:0] pipeline_imag [0:PIPELINE_DEPTH-1];
    logic [1:0] pipeline_gate_type [0:PIPELINE_DEPTH-1];
    logic [PIPELINE_DEPTH-1:0] pipeline_valid;

    // Gate matrices (pre-computed constants)
    localparam real SQRT2_INV = 0.7_071_067_811_865_476;

    // Complex multiplication units
    logic [DATA_WIDTH-1:0] mult_real, mult_imag;
    logic [DATA_WIDTH-1:0] add_real, add_imag;

    // DSP blocks for complex arithmetic
    logic [DATA_WIDTH*2-1:0] dsp_mult_result;
    logic [DATA_WIDTH-1:0] dsp_add_result;

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            pipeline_valid <= '0;
            ready <= 1'b1;
        end else if (enable) begin
            // Pipeline stage advancement
            for (int i = PIPELINE_DEPTH-1; i > 0; i--) begin
                pipeline_real[i] <= pipeline_real[i-1];
                pipeline_imag[i] <= pipeline_imag[i-1];
                pipeline_gate_type[i] <= pipeline_gate_type[i-1];
            end

            // Input stage
            pipeline_real[0] <= state_real_in;
            pipeline_imag[0] <= state_imag_in;
            pipeline_gate_type[0] <= gate_type;

            // Valid signal pipeline
            pipeline_valid <= {{pipeline_valid[PIPELINE_DEPTH-2:0], enable}};
        end
    end

    // Gate operation logic (combinational)
    always_comb begin
        case (pipeline_gate_type[PIPELINE_DEPTH-1])
            2'b00: begin // Hadamard
                state_real_out = (pipeline_real[PIPELINE_DEPTH-1] + pipeline_imag[PIPELINE_DEPTH-1]) * SQRT2_INV;
                state_imag_out = (pipeline_real[PIPELINE_DEPTH-1] - pipeline_imag[PIPELINE_DEPTH-1]) * SQRT2_INV;
            end
            2'b01: begin // Pauli-X
                state_real_out = pipeline_imag[PIPELINE_DEPTH-1];
                state_imag_out = pipeline_real[PIPELINE_DEPTH-1];
            end
            2'b10: begin // Pauli-Y
                state_real_out = -pipeline_imag[PIPELINE_DEPTH-1];
                state_imag_out = pipeline_real[PIPELINE_DEPTH-1];
            end
            2'b11: begin // Pauli-Z
                state_real_out = pipeline_real[PIPELINE_DEPTH-1];
                state_imag_out = -pipeline_imag[PIPELINE_DEPTH-1];
            end
            default: begin
                state_real_out = pipeline_real[PIPELINE_DEPTH-1];
                state_imag_out = pipeline_imag[PIPELINE_DEPTH-1];
            end
        endcase

        valid_out = pipeline_valid[PIPELINE_DEPTH-1];
    end

endmodule
",
            self.config.platform,
            self.config.clock_frequency,
            self.config.data_path_width,
            self.config.data_path_width,
            self.config.pipeline_depth
        )
    }
    /// Generate `OpenCL` code for single qubit gates
    fn generate_single_qubit_opencl(&self) -> String {
        r"
// OpenCL kernel for single qubit gates
__kernel void single_qubit_gate(
    __global float2* state,
    __global const float* gate_matrix,
    const int target_qubit,
    const int num_qubits
) {
    const int global_id = get_global_id(0);
    const int total_states = 1 << num_qubits;

    if (global_id >= total_states / 2) return;

    const int target_mask = 1 << target_qubit;
    const int i = global_id;
    const int j = i | target_mask;

    if ((i & target_mask) == 0) {
        float2 state_i = state[i];
        float2 state_j = state[j];

        // Apply 2x2 gate matrix
        state[i] = (float2)(
            gate_matrix[0] * state_i.x - gate_matrix[1] * state_i.y +
            gate_matrix[2] * state_j.x - gate_matrix[3] * state_j.y,
            gate_matrix[0] * state_i.y + gate_matrix[1] * state_i.x +
            gate_matrix[2] * state_j.y + gate_matrix[3] * state_j.x
        );

        state[j] = (float2)(
            gate_matrix[4] * state_i.x - gate_matrix[5] * state_i.y +
            gate_matrix[6] * state_j.x - gate_matrix[7] * state_j.y,
            gate_matrix[4] * state_i.y + gate_matrix[5] * state_i.x +
            gate_matrix[6] * state_j.y + gate_matrix[7] * state_j.x
        );
    }
}
"
        .to_string()
    }
    /// Register the two-qubit-gate module metadata.
    ///
    /// No HDL generator is implemented for this module yet, so `hdl_code` is
    /// left empty (rather than a stub comment pretending to be synthesizable).
    /// The resource/timing figures are datasheet-style reference estimates.
    /// [`Self::export_hdl`] returns an honest error for modules with no code.
    fn generate_two_qubit_module(&mut self) -> Result<()> {
        let hdl_code = String::new();
        let module = HDLModule {
            name: "two_qubit_gate".to_string(),
            hdl_code,
            resource_utilization: ResourceUtilization {
                luts: 2500,
                flip_flops: 1200,
                dsp_blocks: 16,
                bram_kb: 8,
                utilization_percent: 12.0,
            },
            timing_info: TimingInfo {
                critical_path_delay: 4.5,
                setup_slack: 0.5,
                hold_slack: 1.2,
                max_frequency: 222.2,
            },
            module_type: ModuleType::TwoQubitGate,
        };
        self.hdl_modules
            .insert("two_qubit_gate".to_string(), module);
        Ok(())
    }
    /// Register the control-unit module metadata (no HDL generator implemented).
    ///
    /// See [`Self::generate_two_qubit_module`] for why `hdl_code` is empty.
    fn generate_control_unit_module(&mut self) -> Result<()> {
        let hdl_code = String::new();
        let module = HDLModule {
            name: "control_unit".to_string(),
            hdl_code,
            resource_utilization: ResourceUtilization {
                luts: 5000,
                flip_flops: 3000,
                dsp_blocks: 4,
                bram_kb: 16,
                utilization_percent: 25.0,
            },
            timing_info: TimingInfo {
                critical_path_delay: 2.8,
                setup_slack: 1.2,
                hold_slack: 2.0,
                max_frequency: 357.1,
            },
            module_type: ModuleType::ControlUnit,
        };
        self.hdl_modules.insert("control_unit".to_string(), module);
        Ok(())
    }
    /// Register the memory-controller module metadata (no HDL generator).
    ///
    /// See [`Self::generate_two_qubit_module`] for why `hdl_code` is empty.
    fn generate_memory_controller_module(&mut self) -> Result<()> {
        let hdl_code = String::new();
        let module = HDLModule {
            name: "memory_controller".to_string(),
            hdl_code,
            resource_utilization: ResourceUtilization {
                luts: 3000,
                flip_flops: 2000,
                dsp_blocks: 0,
                bram_kb: 32,
                utilization_percent: 15.0,
            },
            timing_info: TimingInfo {
                critical_path_delay: 3.5,
                setup_slack: 0.9,
                hold_slack: 1.8,
                max_frequency: 285.7,
            },
            module_type: ModuleType::MemoryController,
        };
        self.hdl_modules
            .insert("memory_controller".to_string(), module);
        Ok(())
    }
    /// Register the arithmetic-unit module metadata (no HDL generator).
    ///
    /// See [`Self::generate_two_qubit_module`] for why `hdl_code` is empty.
    fn generate_arithmetic_unit_module(&mut self) -> Result<()> {
        let hdl_code = String::new();
        let module = HDLModule {
            name: "arithmetic_unit".to_string(),
            hdl_code,
            resource_utilization: ResourceUtilization {
                luts: 4000,
                flip_flops: 2500,
                dsp_blocks: 32,
                bram_kb: 4,
                utilization_percent: 20.0,
            },
            timing_info: TimingInfo {
                critical_path_delay: 3.8,
                setup_slack: 0.7,
                hold_slack: 1.5,
                max_frequency: 263.2,
            },
            module_type: ModuleType::ArithmeticUnit,
        };
        self.hdl_modules
            .insert("arithmetic_unit".to_string(), module);
        Ok(())
    }
    /// Load default bitstream (model bookkeeping only; no real device program).
    ///
    /// In the CPU simulation there is no board to program, so this only records
    /// the selected configuration. No fabricated configuration latency is added.
    fn load_default_bitstream(&mut self) -> Result<()> {
        self.bitstream_manager.current_config = Some("quantum_basic".to_string());
        self.stats.reconfigurations += 1;
        Ok(())
    }
    /// Execute a quantum circuit (CPU numerical simulation of the FPGA gate math).
    pub fn execute_circuit(&mut self, circuit: &InterfaceCircuit) -> Result<Array1<Complex64>> {
        let start_time = std::time::Instant::now();
        let mut state = Array1::zeros(1 << circuit.num_qubits);
        state[0] = Complex64::new(1.0, 0.0);
        for gate in &circuit.gates {
            state = self.apply_gate_fpga(&state, gate)?;
        }
        let execution_time = start_time.elapsed().as_secs_f64() * 1000.0;
        // Honest: in a CPU simulation we cannot measure FPGA clock cycles. We
        // record the real measured wall-time and count gates applied; we do not
        // synthesize a clock-cycle figure from CPU time.
        self.stats
            .update_operation(execution_time, circuit.gates.len() as u64);
        self.update_utilization();
        Ok(state)
    }
    /// Apply a quantum gate (CPU numerical simulation of the FPGA gate math).
    fn apply_gate_fpga(
        &mut self,
        state: &Array1<Complex64>,
        gate: &InterfaceGate,
    ) -> Result<Array1<Complex64>> {
        let unit_id = self.select_processing_unit(gate)?;
        let result = match &gate.gate_type {
            InterfaceGateType::Hadamard
            | InterfaceGateType::PauliX
            | InterfaceGateType::PauliY
            | InterfaceGateType::PauliZ => self.apply_single_qubit_gate_fpga(state, gate, unit_id),
            InterfaceGateType::CNOT | InterfaceGateType::CZ => {
                self.apply_two_qubit_gate_fpga(state, gate, unit_id)
            }
            InterfaceGateType::RX(_) | InterfaceGateType::RY(_) | InterfaceGateType::RZ(_) => {
                self.apply_rotation_gate_fpga(state, gate, unit_id)
            }
            other => {
                return Err(SimulatorError::UnsupportedOperation(format!(
                    "FPGA simulation: gate {other:?} is not implemented"
                )));
            }
        };
        if result.is_ok() {
            self.processing_units[unit_id].utilization += 1.0;
        }
        result
    }
    /// Select processing unit for gate execution
    fn select_processing_unit(&self, gate: &InterfaceGate) -> Result<usize> {
        let mut best_unit = 0;
        let mut min_utilization = f64::INFINITY;
        for (i, unit) in self.processing_units.iter().enumerate() {
            if unit.supported_gates.contains(&gate.gate_type) && unit.utilization < min_utilization
            {
                best_unit = i;
                min_utilization = unit.utilization;
            }
        }
        Ok(best_unit)
    }
    /// Apply a single-qubit gate (CPU numerical simulation of the gate math).
    ///
    /// Uses the gate's canonical 2x2 unitary, so it correctly handles every
    /// single-qubit gate including rotations `RX/RY/RZ` (the previous version
    /// silently no-op'd rotations). No fabricated pipeline latency is injected.
    pub fn apply_single_qubit_gate_fpga(
        &self,
        state: &Array1<Complex64>,
        gate: &InterfaceGate,
        _unit_id: usize,
    ) -> Result<Array1<Complex64>> {
        if gate.qubits.is_empty() {
            return Err(SimulatorError::InvalidInput(
                "single-qubit gate has no target qubit".to_string(),
            ));
        }
        let target_qubit = gate.qubits[0];
        let num_qubits = state.len().trailing_zeros() as usize;
        if state.len() != 1usize << num_qubits {
            return Err(SimulatorError::DimensionMismatch(format!(
                "State length {} is not a power of two",
                state.len()
            )));
        }
        if target_qubit >= num_qubits {
            return Err(SimulatorError::IndexOutOfBounds(target_qubit));
        }
        let unitary = gate.unitary_matrix()?;
        let mut result = state.clone();
        let target_mask = 1usize << target_qubit;
        for i in 0..state.len() {
            if i & target_mask == 0 {
                let j = i | target_mask;
                let amp_0 = state[i];
                let amp_1 = state[j];
                result[i] = unitary[[0, 0]] * amp_0 + unitary[[0, 1]] * amp_1;
                result[j] = unitary[[1, 0]] * amp_0 + unitary[[1, 1]] * amp_1;
            }
        }
        Ok(result)
    }
    /// Apply a two-qubit gate (CPU numerical simulation of the FPGA gate math).
    ///
    /// No fabricated pipeline latency is injected.
    fn apply_two_qubit_gate_fpga(
        &self,
        state: &Array1<Complex64>,
        gate: &InterfaceGate,
        _unit_id: usize,
    ) -> Result<Array1<Complex64>> {
        if gate.qubits.len() < 2 {
            return Err(SimulatorError::InvalidInput(
                "two-qubit gate requires two qubits".to_string(),
            ));
        }
        let control = gate.qubits[0];
        let target = gate.qubits[1];
        let mut result = state.clone();
        match gate.gate_type {
            InterfaceGateType::CNOT => {
                for i in 0..state.len() {
                    if ((i >> control) & 1) == 1 {
                        let j = i ^ (1 << target);
                        if j < state.len() && i != j {
                            let temp = result[i];
                            result[i] = result[j];
                            result[j] = temp;
                        }
                    }
                }
            }
            InterfaceGateType::CZ => {
                for i in 0..state.len() {
                    if ((i >> control) & 1) == 1 && ((i >> target) & 1) == 1 {
                        result[i] = -result[i];
                    }
                }
            }
            _ => {}
        }
        Ok(result)
    }
    /// Apply rotation gate using FPGA
    fn apply_rotation_gate_fpga(
        &self,
        state: &Array1<Complex64>,
        gate: &InterfaceGate,
        unit_id: usize,
    ) -> Result<Array1<Complex64>> {
        self.apply_single_qubit_gate_fpga(state, gate, unit_id)
    }
    /// Update FPGA utilization metrics from the model's own bookkeeping.
    ///
    /// Only `fpga_utilization` (derived from the per-unit operation counts the
    /// model actually tracks) is set here. `pipeline_efficiency` and
    /// `memory_bandwidth_utilization` are intentionally left untouched: there is
    /// no real pipeline or memory bus to measure in a CPU simulation, so we do
    /// NOT fabricate fixed efficiency numbers for them.
    fn update_utilization(&mut self) {
        let total_utilization: f64 = self.processing_units.iter().map(|u| u.utilization).sum();
        self.stats.fpga_utilization = total_utilization / self.processing_units.len() as f64;
    }
    /// Get device information
    #[must_use]
    pub const fn get_device_info(&self) -> &FPGADeviceInfo {
        &self.device_info
    }
    /// Get performance statistics
    #[must_use]
    pub const fn get_stats(&self) -> &FPGAStats {
        &self.stats
    }
    /// Get HDL modules
    #[must_use]
    pub const fn get_hdl_modules(&self) -> &HashMap<String, HDLModule> {
        &self.hdl_modules
    }
    /// Select a different bitstream configuration (model bookkeeping only).
    ///
    /// In the CPU simulation there is no board to reprogram, so this validates
    /// and records the selection without fabricating a reconfiguration latency.
    pub fn reconfigure(&mut self, bitstream_name: &str) -> Result<()> {
        if !self
            .bitstream_manager
            .bitstreams
            .contains_key(bitstream_name)
        {
            return Err(SimulatorError::InvalidInput(format!(
                "Bitstream {bitstream_name} not found"
            )));
        }
        self.bitstream_manager.current_config = Some(bitstream_name.to_string());
        self.stats.reconfigurations += 1;
        Ok(())
    }
    /// Whether a *real* FPGA board is available.
    ///
    /// HONEST: this build links no FPGA runtime, so a physical board is never
    /// available. This returns `false` even when the CPU `Simulation` device is
    /// in use - that is a numerical model, not a programmed FPGA.
    #[must_use]
    pub const fn is_fpga_available(&self) -> bool {
        false
    }
    /// Export HDL code for synthesis.
    ///
    /// Returns an honest error for unknown modules and for modules that have no
    /// HDL generator implemented yet (empty `hdl_code`) - we never hand back a
    /// stub comment dressed up as synthesizable HDL.
    pub fn export_hdl(&self, module_name: &str) -> Result<String> {
        let module = self.hdl_modules.get(module_name).ok_or_else(|| {
            SimulatorError::InvalidInput(format!("Module {module_name} not found"))
        })?;
        if module.hdl_code.is_empty() {
            return Err(SimulatorError::UnsupportedOperation(format!(
                "FPGA HDL export: no HDL generator implemented for module \
                 '{module_name}' (only single_qubit_gate is generated)"
            )));
        }
        Ok(module.hdl_code.clone())
    }
}
/// FPGA bitstream
#[derive(Debug, Clone)]
pub struct Bitstream {
    /// Bitstream name
    pub name: String,
    /// Target configuration
    pub target_config: String,
    /// Size (KB)
    pub size_kb: usize,
    /// Configuration time (ms)
    pub config_time_ms: f64,
    /// Supported quantum algorithms
    pub supported_algorithms: Vec<String>,
}
/// Arithmetic precision types
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ArithmeticPrecision {
    Fixed8,
    Fixed16,
    Fixed32,
    Float16,
    Float32,
    Float64,
    CustomFixed(u32),
    CustomFloat(u32, u32),
}
/// Pipeline operations
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PipelineOperation {
    Fetch,
    Decode,
    AddressCalculation,
    MemoryRead,
    GateExecution,
    MemoryWrite,
    Writeback,
}
/// HDL module representation
#[derive(Debug, Clone)]
pub struct HDLModule {
    /// Module name
    pub name: String,
    /// HDL code
    pub hdl_code: String,
    /// Resource utilization
    pub resource_utilization: ResourceUtilization,
    /// Timing information
    pub timing_info: TimingInfo,
    /// Module type
    pub module_type: ModuleType,
}
/// Memory interface types
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemoryInterfaceType {
    DDR4,
    DDR5,
    HBM2,
    HBM3,
    GDDR6,
    OnChipRAM,
}
/// Hardware description language targets
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HDLTarget {
    Verilog,
    SystemVerilog,
    VHDL,
    Chisel,
    HLS,
    OpenCL,
}
/// Module types
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ModuleType {
    SingleQubitGate,
    TwoQubitGate,
    ControlUnit,
    MemoryController,
    ArithmeticUnit,
    StateVectorUnit,
}
/// Resource utilization
#[derive(Debug, Clone, Default)]
pub struct ResourceUtilization {
    /// LUTs used
    pub luts: usize,
    /// FFs used
    pub flip_flops: usize,
    /// DSP blocks used
    pub dsp_blocks: usize,
    /// Block RAM used (KB)
    pub bram_kb: usize,
    /// Utilization percentage
    pub utilization_percent: f64,
}
/// FPGA memory manager
#[derive(Debug, Clone)]
pub struct FPGAMemoryManager {
    /// On-chip memory pools
    pub onchip_pools: HashMap<String, MemoryPool>,
    /// External memory interfaces
    pub external_interfaces: Vec<ExternalMemoryInterface>,
    /// Memory access scheduler
    pub access_scheduler: MemoryAccessScheduler,
    /// Total available memory (KB)
    pub total_memory_kb: usize,
    /// Used memory (KB)
    pub used_memory_kb: usize,
}
/// FPGA performance statistics
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct FPGAStats {
    /// Total gate operations
    pub total_gate_operations: usize,
    /// Total execution time (ms)
    pub total_execution_time: f64,
    /// Average gate time (ns)
    pub avg_gate_time: f64,
    /// Clock cycles consumed
    pub total_clock_cycles: u64,
    /// FPGA utilization
    pub fpga_utilization: f64,
    /// Memory bandwidth utilization
    pub memory_bandwidth_utilization: f64,
    /// Pipeline efficiency
    pub pipeline_efficiency: f64,
    /// Reconfiguration count
    pub reconfigurations: usize,
    /// Total reconfiguration time (ms)
    pub total_reconfig_time: f64,
    /// Power consumption (W)
    pub power_consumption: f64,
}
impl FPGAStats {
    /// Update statistics after operation
    pub fn update_operation(&mut self, execution_time: f64, clock_cycles: u64) {
        self.total_gate_operations += 1;
        self.total_execution_time += execution_time;
        self.avg_gate_time =
            (self.total_execution_time * 1_000_000.0) / self.total_gate_operations as f64;
        self.total_clock_cycles += clock_cycles;
    }
    /// Calculate performance metrics
    #[must_use]
    pub fn get_performance_metrics(&self) -> HashMap<String, f64> {
        let mut metrics = HashMap::new();
        if self.total_execution_time > 0.0 {
            metrics.insert(
                "operations_per_second".to_string(),
                self.total_gate_operations as f64 / (self.total_execution_time / 1000.0),
            );
            metrics.insert(
                "cycles_per_operation".to_string(),
                self.total_clock_cycles as f64 / self.total_gate_operations as f64,
            );
        }
        metrics.insert("fpga_utilization".to_string(), self.fpga_utilization);
        metrics.insert("pipeline_efficiency".to_string(), self.pipeline_efficiency);
        metrics.insert(
            "memory_bandwidth_utilization".to_string(),
            self.memory_bandwidth_utilization,
        );
        if self.power_consumption > 0.0 && self.total_execution_time > 0.0 {
            metrics.insert(
                "power_efficiency".to_string(),
                self.total_gate_operations as f64
                    / (self.power_consumption * self.total_execution_time / 1000.0),
            );
        }
        metrics
    }
}
/// FPGA configuration
#[derive(Debug, Clone)]
pub struct FPGAConfig {
    /// Target FPGA platform
    pub platform: FPGAPlatform,
    /// Clock frequency (MHz)
    pub clock_frequency: f64,
    /// Number of processing units
    pub num_processing_units: usize,
    /// Memory bandwidth (GB/s)
    pub memory_bandwidth: f64,
    /// Enable pipelining
    pub enable_pipelining: bool,
    /// Pipeline depth
    pub pipeline_depth: usize,
    /// Data path width (bits)
    pub data_path_width: usize,
    /// Enable DSP optimization
    pub enable_dsp_optimization: bool,
    /// Enable block RAM optimization
    pub enable_bram_optimization: bool,
    /// Maximum state vector size
    pub max_state_size: usize,
    /// Enable real-time processing
    pub enable_realtime: bool,
    /// Hardware description language
    pub hdl_target: HDLTarget,
}
/// External memory interface
#[derive(Debug, Clone)]
pub struct ExternalMemoryInterface {
    /// Interface ID
    pub interface_id: usize,
    /// Interface type
    pub interface_type: MemoryInterfaceType,
    /// Controller module
    pub controller: String,
    /// Current utilization
    pub utilization: f64,
}