quantrs2-circuit 0.1.3

//! Distributed Circuit Execution Framework
//!
//! This module provides infrastructure for executing quantum circuits across
//! multiple quantum devices, simulators, or cloud services in a distributed manner.

use crate::builder::Circuit;
use quantrs2_core::{
    error::{QuantRS2Error, QuantRS2Result},
    qubit::QubitId,
};
use scirs2_core::Complex64;
use std::collections::HashMap;
use std::time::{Duration, Instant};

/// Internal record tracking a submitted job's lifecycle.
#[derive(Debug, Clone)]
struct JobRecord {
    /// Current execution status
    status: ExecutionStatus,
    /// Identifiers of the backends that were selected for this job
    backends: Vec<String>,
    /// Monotonic instant at which the job was submitted
    submitted_at: std::time::Instant,
}

/// A distributed quantum circuit execution engine
///
/// This manages execution of quantum circuits across multiple backends,
/// handling load balancing, fault tolerance, and result aggregation.
#[derive(Debug)]
pub struct DistributedExecutor {
    /// Available execution backends
    pub backends: Vec<ExecutionBackend>,
    /// Load balancing strategy
    pub load_balancer: LoadBalancer,
    /// Fault tolerance configuration
    pub fault_tolerance: FaultToleranceConfig,
    /// Execution scheduling policy
    pub scheduler: ExecutionScheduler,
    /// Resource management
    pub resource_manager: ResourceManager,
    /// In-memory job registry mapping job ID → job record
    job_registry: HashMap<String, JobRecord>,
}

/// A quantum execution backend (device, simulator, or cloud service)
#[derive(Debug, Clone)]
pub struct ExecutionBackend {
    /// Unique identifier for the backend
    pub id: String,
    /// Type of backend
    pub backend_type: BackendType,
    /// Current status
    pub status: BackendStatus,
    /// Performance characteristics
    pub performance: BackendPerformance,
    /// Queue information
    pub queue_info: QueueInfo,
    /// Supported operations
    pub capabilities: BackendCapabilities,
    /// Network configuration
    pub network_config: NetworkConfig,
}

/// Types of quantum execution backends
#[derive(Debug, Clone, PartialEq)]
pub enum BackendType {
    /// Physical quantum hardware
    Hardware {
        vendor: String,
        model: String,
        location: String,
    },
    /// Quantum simulator
    Simulator {
        simulator_type: SimulatorType,
        host: String,
    },
    /// Cloud quantum service
    CloudService {
        provider: String,
        service_name: String,
        region: String,
    },
    /// Hybrid classical-quantum system
    Hybrid {
        quantum_backend: Box<Self>,
        classical_resources: ClassicalResources,
    },
}

/// Types of quantum simulators
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SimulatorType {
    StateVector,
    DensityMatrix,
    TensorNetwork,
    StabilunerformCode,
    MatrixProductState,
    Custom(String),
}

/// Classical computing resources for hybrid systems
#[derive(Debug, Clone, PartialEq)]
pub struct ClassicalResources {
    /// CPU cores available
    pub cpu_cores: usize,
    /// Memory in GB
    pub memory_gb: f64,
    /// GPU information
    pub gpus: Vec<GPUInfo>,
    /// Storage capacity in GB
    pub storage_gb: f64,
}

/// GPU information
#[derive(Debug, Clone, PartialEq)]
pub struct GPUInfo {
    /// GPU model
    pub model: String,
    /// Memory in GB
    pub memory_gb: f64,
    /// Compute capability
    pub compute_capability: String,
}

/// Current status of a backend
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BackendStatus {
    /// Available for execution
    Available,
    /// Currently busy
    Busy,
    /// Temporarily unavailable
    Unavailable,
    /// Under maintenance
    Maintenance,
    /// Offline/disconnected
    Offline,
    /// Error state
    Error(String),
}

/// Performance characteristics of a backend
#[derive(Debug, Clone)]
pub struct BackendPerformance {
    /// Maximum number of qubits
    pub max_qubits: usize,
    /// Maximum circuit depth
    pub max_depth: usize,
    /// Gate fidelities
    pub gate_fidelities: HashMap<String, f64>,
    /// Coherence times (in microseconds)
    pub coherence_times: HashMap<String, f64>,
    /// Execution time estimates
    pub execution_time_model: ExecutionTimeModel,
    /// Throughput (circuits per second)
    pub throughput: f64,
}

/// Model for predicting execution times
#[derive(Debug, Clone)]
pub struct ExecutionTimeModel {
    /// Base execution time (seconds)
    pub base_time: f64,
    /// Time per gate (seconds)
    pub time_per_gate: f64,
    /// Time per qubit (seconds)
    pub time_per_qubit: f64,
    /// Time per measurement (seconds)
    pub time_per_measurement: f64,
    /// Network latency (seconds)
    pub network_latency: f64,
}

/// Queue information for a backend
#[derive(Debug, Clone)]
pub struct QueueInfo {
    /// Current queue length
    pub queue_length: usize,
    /// Estimated wait time (seconds)
    pub estimated_wait_time: f64,
    /// Maximum queue size
    pub max_queue_size: usize,
    /// Priority levels supported
    pub priority_levels: Vec<Priority>,
}

/// Execution priority levels
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Priority {
    Low,
    Normal,
    High,
    Critical,
}

/// Backend capabilities
#[derive(Debug, Clone)]
pub struct BackendCapabilities {
    /// Supported gate set
    pub supported_gates: Vec<String>,
    /// Supports mid-circuit measurements
    pub mid_circuit_measurements: bool,
    /// Supports classical control flow
    pub classical_control: bool,
    /// Supports reset operations
    pub reset_operations: bool,
    /// Connectivity graph
    pub connectivity: ConnectivityGraph,
    /// Noise characteristics
    pub noise_model: Option<NoiseCharacteristics>,
}

/// Qubit connectivity graph
#[derive(Debug, Clone)]
pub struct ConnectivityGraph {
    /// Number of qubits
    pub num_qubits: usize,
    /// Edges representing allowed two-qubit gates
    pub edges: Vec<(usize, usize)>,
    /// Connectivity type
    pub topology: TopologyType,
}

/// Types of qubit connectivity topologies
#[derive(Debug, Clone, PartialEq)]
pub enum TopologyType {
    /// Linear chain
    Linear,
    /// 2D grid
    Grid2D { rows: usize, cols: usize },
    /// All-to-all connectivity
    AllToAll,
    /// Random graph
    Random { density: f64 },
    /// Custom topology
    Custom,
}

/// Noise characteristics of a backend
#[derive(Debug, Clone)]
pub struct NoiseCharacteristics {
    /// Single-qubit gate error rates
    pub single_qubit_errors: HashMap<String, f64>,
    /// Two-qubit gate error rates
    pub two_qubit_errors: HashMap<String, f64>,
    /// Measurement error rates
    pub measurement_errors: Vec<f64>,
    /// Decoherence times
    pub decoherence_times: Vec<f64>,
}

/// Network configuration for backend communication
#[derive(Debug, Clone)]
pub struct NetworkConfig {
    /// Endpoint URL
    pub endpoint: String,
    /// Authentication credentials
    pub credentials: Credentials,
    /// Timeout settings
    pub timeouts: TimeoutConfig,
    /// Retry policy
    pub retry_policy: RetryPolicy,
}

/// Authentication credentials
#[derive(Debug, Clone)]
pub struct Credentials {
    /// Authentication type
    pub auth_type: AuthenticationType,
    /// API key (if applicable)
    pub api_key: Option<String>,
    /// Token (if applicable)
    pub token: Option<String>,
    /// Username/password (if applicable)
    pub username_password: Option<(String, String)>,
}

/// Types of authentication
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AuthenticationType {
    ApiKey,
    Token,
    UsernamePassword,
    Certificate,
    None,
}

/// Timeout configuration
#[derive(Debug, Clone)]
pub struct TimeoutConfig {
    /// Connection timeout (seconds)
    pub connection_timeout: f64,
    /// Request timeout (seconds)
    pub request_timeout: f64,
    /// Total timeout (seconds)
    pub total_timeout: f64,
}

/// Retry policy configuration
#[derive(Debug, Clone)]
pub struct RetryPolicy {
    /// Maximum number of retries
    pub max_retries: usize,
    /// Base delay between retries (seconds)
    pub base_delay: f64,
    /// Backoff strategy
    pub backoff_strategy: BackoffStrategy,
    /// Retryable error types
    pub retryable_errors: Vec<ErrorType>,
}

/// Backoff strategies for retries
#[derive(Debug, Clone, PartialEq)]
pub enum BackoffStrategy {
    /// Fixed delay
    Fixed,
    /// Linear backoff
    Linear,
    /// Exponential backoff
    Exponential { multiplier: f64 },
    /// Random jitter
    Jitter { max_jitter: f64 },
}

/// Types of errors that can be retried
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErrorType {
    NetworkError,
    TimeoutError,
    ServiceUnavailable,
    RateLimited,
    InternalServerError,
}

/// Load balancing strategies
#[derive(Debug, Clone)]
pub struct LoadBalancer {
    /// Balancing strategy
    pub strategy: LoadBalancingStrategy,
    /// Health check configuration
    pub health_check: HealthCheckConfig,
    /// Metrics collection
    pub metrics: MetricsConfig,
}

/// Load balancing strategies
#[derive(Debug, Clone, PartialEq)]
pub enum LoadBalancingStrategy {
    /// Round robin
    RoundRobin,
    /// Least connections
    LeastConnections,
    /// Least queue time
    LeastQueueTime,
    /// Best performance
    BestPerformance,
    /// Weighted round robin
    WeightedRoundRobin(HashMap<String, f64>),
    /// Custom strategy
    Custom(String),
}

/// Health check configuration
#[derive(Debug, Clone)]
pub struct HealthCheckConfig {
    /// Health check interval (seconds)
    pub interval: f64,
    /// Health check timeout (seconds)
    pub timeout: f64,
    /// Number of failed checks before marking unhealthy
    pub failure_threshold: usize,
    /// Number of successful checks before marking healthy
    pub success_threshold: usize,
}

/// Metrics collection configuration
#[derive(Debug, Clone)]
pub struct MetricsConfig {
    /// Enable metrics collection
    pub enabled: bool,
    /// Metrics collection interval (seconds)
    pub collection_interval: f64,
    /// Metrics retention period (seconds)
    pub retention_period: f64,
    /// Metrics storage backend
    pub storage_backend: MetricsStorage,
}

/// Metrics storage backends
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MetricsStorage {
    InMemory,
    File(String),
    Database(String),
    CloudStorage(String),
}

/// Fault tolerance configuration
#[derive(Debug, Clone)]
pub struct FaultToleranceConfig {
    /// Enable automatic failover
    pub enable_failover: bool,
    /// Circuit redundancy level
    pub redundancy_level: usize,
    /// Error correction strategy
    pub error_correction: ErrorCorrectionStrategy,
    /// Failure detection configuration
    pub failure_detection: FailureDetectionConfig,
}

/// Error correction strategies
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErrorCorrectionStrategy {
    /// No error correction
    None,
    /// Majority voting
    MajorityVoting,
    /// Quantum error correction
    QuantumErrorCorrection,
    /// Classical post-processing
    ClassicalPostProcessing,
    /// Custom strategy
    Custom(String),
}

/// Failure detection configuration
#[derive(Debug, Clone)]
pub struct FailureDetectionConfig {
    /// Detection methods
    pub detection_methods: Vec<FailureDetectionMethod>,
    /// Detection threshold
    pub detection_threshold: f64,
    /// Detection window (seconds)
    pub detection_window: f64,
}

/// Failure detection methods
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FailureDetectionMethod {
    /// Error rate monitoring
    ErrorRateMonitoring,
    /// Latency monitoring
    LatencyMonitoring,
    /// Result validation
    ResultValidation,
    /// Health check failures
    HealthCheckFailures,
}

/// Execution scheduler
#[derive(Debug, Clone)]
pub struct ExecutionScheduler {
    /// Scheduling policy
    pub policy: SchedulingPolicy,
    /// Priority queue configuration
    pub priority_queue: PriorityQueueConfig,
    /// Resource allocation strategy
    pub resource_allocation: ResourceAllocationStrategy,
}

/// Scheduling policies
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SchedulingPolicy {
    /// First-come, first-served
    FCFS,
    /// Shortest job first
    SJF,
    /// Priority-based scheduling
    Priority,
    /// Fair share scheduling
    FairShare,
    /// Deadline-aware scheduling
    DeadlineAware,
    /// Custom policy
    Custom(String),
}

/// Priority queue configuration
#[derive(Debug, Clone)]
pub struct PriorityQueueConfig {
    /// Maximum queue size per priority
    pub max_size_per_priority: HashMap<Priority, usize>,
    /// Aging factor for priority adjustment
    pub aging_factor: f64,
    /// Priority boost interval (seconds)
    pub priority_boost_interval: f64,
}

/// Resource allocation strategies
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResourceAllocationStrategy {
    /// Best fit
    BestFit,
    /// First fit
    FirstFit,
    /// Worst fit
    WorstFit,
    /// Next fit
    NextFit,
    /// Custom allocation
    Custom(String),
}

/// Resource manager
#[derive(Debug, Clone)]
pub struct ResourceManager {
    /// Resource pool
    pub resource_pool: ResourcePool,
    /// Allocation policies
    pub allocation_policies: AllocationPolicies,
    /// Usage tracking
    pub usage_tracking: UsageTracking,
}

/// Resource pool information
#[derive(Debug, Clone)]
pub struct ResourcePool {
    /// Total available qubits across all backends
    pub total_qubits: usize,
    /// Available execution slots
    pub available_slots: usize,
    /// Memory pool (in GB)
    pub memory_pool: f64,
    /// Compute pool (in CPU hours)
    pub compute_pool: f64,
}

/// Resource allocation policies
#[derive(Debug, Clone)]
pub struct AllocationPolicies {
    /// Maximum qubits per user
    pub max_qubits_per_user: Option<usize>,
    /// Maximum execution time per job
    pub max_execution_time: Option<f64>,
    /// Fair share allocation
    pub fair_share: bool,
    /// Reserved resources for high-priority jobs
    pub reserved_resources: f64,
}

/// Usage tracking configuration
#[derive(Debug, Clone)]
pub struct UsageTracking {
    /// Track per-user usage
    pub per_user_tracking: bool,
    /// Track per-project usage
    pub per_project_tracking: bool,
    /// Usage reporting interval (seconds)
    pub reporting_interval: f64,
    /// Usage data retention (seconds)
    pub retention_period: f64,
}

/// Distributed execution job
#[derive(Debug, Clone)]
pub struct DistributedJob<const N: usize> {
    /// Job identifier
    pub id: String,
    /// Circuit to execute
    pub circuit: Circuit<N>,
    /// Execution parameters
    pub parameters: ExecutionParameters,
    /// Job priority
    pub priority: Priority,
    /// Target backends (if specified)
    pub target_backends: Option<Vec<String>>,
    /// Submission time
    pub submitted_at: Instant,
    /// Deadline (if any)
    pub deadline: Option<Instant>,
}

/// Execution parameters for a job
#[derive(Debug, Clone)]
pub struct ExecutionParameters {
    /// Number of shots
    pub shots: usize,
    /// Optimization level
    pub optimization_level: usize,
    /// Error mitigation techniques
    pub error_mitigation: Vec<ErrorMitigation>,
    /// Result format
    pub result_format: ResultFormat,
    /// Memory requirements
    pub memory_requirement: Option<f64>,
}

/// Error mitigation techniques
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErrorMitigation {
    /// Readout error mitigation
    ReadoutErrorMitigation,
    /// Zero-noise extrapolation
    ZeroNoiseExtrapolation,
    /// Clifford data regression
    CliffordDataRegression,
    /// Symmetry verification
    SymmetryVerification,
    /// Custom mitigation
    Custom(String),
}

/// Result format options
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResultFormat {
    /// Raw counts
    Counts,
    /// Probabilities
    Probabilities,
    /// Statevector (if available)
    Statevector,
    /// Expectation values
    ExpectationValues,
    /// Custom format
    Custom(String),
}

/// Execution result from distributed system
#[derive(Debug, Clone)]
pub struct DistributedResult {
    /// Job ID
    pub job_id: String,
    /// Execution status
    pub status: ExecutionStatus,
    /// Results from each backend
    pub backend_results: HashMap<String, BackendResult>,
    /// Aggregated final result
    pub final_result: Option<AggregatedResult>,
    /// Execution metadata
    pub metadata: ExecutionMetadata,
}

/// Execution status
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ExecutionStatus {
    /// Job queued
    Queued,
    /// Job running
    Running,
    /// Job completed successfully
    Completed,
    /// Job failed
    Failed(String),
    /// Job cancelled
    Cancelled,
    /// Job timed out
    TimedOut,
}

/// Result from a single backend
#[derive(Debug, Clone)]
pub struct BackendResult {
    /// Backend ID
    pub backend_id: String,
    /// Execution status on this backend
    pub status: ExecutionStatus,
    /// Raw measurement results
    pub measurements: Option<Vec<Vec<bool>>>,
    /// Probability distributions
    pub probabilities: Option<HashMap<String, f64>>,
    /// Execution time
    pub execution_time: Duration,
    /// Error information (if any)
    pub error: Option<String>,
}

/// Aggregated result across multiple backends
#[derive(Debug, Clone)]
pub struct AggregatedResult {
    /// Combined measurement statistics
    pub combined_measurements: HashMap<String, f64>,
    /// Error estimates
    pub error_estimates: HashMap<String, f64>,
    /// Confidence intervals
    pub confidence_intervals: HashMap<String, (f64, f64)>,
    /// Quality metrics
    pub quality_metrics: QualityMetrics,
}

/// Quality metrics for results
#[derive(Debug, Clone)]
pub struct QualityMetrics {
    /// Statistical significance
    pub statistical_significance: f64,
    /// Consistency across backends
    pub consistency_score: f64,
    /// Estimated fidelity
    pub estimated_fidelity: f64,
    /// Error mitigation effectiveness
    pub mitigation_effectiveness: f64,
}

/// Execution metadata
#[derive(Debug, Clone)]
pub struct ExecutionMetadata {
    /// Total execution time
    pub total_time: Duration,
    /// Queue wait time
    pub queue_time: Duration,
    /// Backends used
    pub backends_used: Vec<String>,
    /// Resource usage
    pub resource_usage: ResourceUsage,
    /// Cost information
    pub cost_info: Option<CostInfo>,
}

/// Resource usage information
#[derive(Debug, Clone)]
pub struct ResourceUsage {
    /// CPU hours used
    pub cpu_hours: f64,
    /// Memory-hours used
    pub memory_hours: f64,
    /// Qubit-hours used
    pub qubit_hours: f64,
    /// Network bandwidth used (GB)
    pub network_usage: f64,
}

/// Cost information
#[derive(Debug, Clone)]
pub struct CostInfo {
    /// Total cost
    pub total_cost: f64,
    /// Cost breakdown by resource
    pub cost_breakdown: HashMap<String, f64>,
    /// Currency
    pub currency: String,
}

impl DistributedExecutor {
    /// Create a new distributed executor
    #[must_use]
    pub fn new() -> Self {
        Self {
            backends: Vec::new(),
            load_balancer: LoadBalancer {
                strategy: LoadBalancingStrategy::RoundRobin,
                health_check: HealthCheckConfig {
                    interval: 30.0,
                    timeout: 5.0,
                    failure_threshold: 3,
                    success_threshold: 2,
                },
                metrics: MetricsConfig {
                    enabled: true,
                    collection_interval: 60.0,
                    retention_period: 3600.0 * 24.0, // 24 hours
                    storage_backend: MetricsStorage::InMemory,
                },
            },
            fault_tolerance: FaultToleranceConfig {
                enable_failover: true,
                redundancy_level: 1,
                error_correction: ErrorCorrectionStrategy::MajorityVoting,
                failure_detection: FailureDetectionConfig {
                    detection_methods: vec![
                        FailureDetectionMethod::ErrorRateMonitoring,
                        FailureDetectionMethod::LatencyMonitoring,
                    ],
                    detection_threshold: 0.1,
                    detection_window: 300.0,
                },
            },
            scheduler: ExecutionScheduler {
                policy: SchedulingPolicy::Priority,
                priority_queue: PriorityQueueConfig {
                    max_size_per_priority: {
                        let mut map = HashMap::new();
                        map.insert(Priority::Critical, 10);
                        map.insert(Priority::High, 50);
                        map.insert(Priority::Normal, 200);
                        map.insert(Priority::Low, 1000);
                        map
                    },
                    aging_factor: 0.1,
                    priority_boost_interval: 3600.0, // 1 hour
                },
                resource_allocation: ResourceAllocationStrategy::BestFit,
            },
            resource_manager: ResourceManager {
                resource_pool: ResourcePool {
                    total_qubits: 0,
                    available_slots: 0,
                    memory_pool: 0.0,
                    compute_pool: 0.0,
                },
                allocation_policies: AllocationPolicies {
                    max_qubits_per_user: Some(100),
                    max_execution_time: Some(3600.0), // 1 hour
                    fair_share: true,
                    reserved_resources: 0.1, // 10% reserved
                },
                usage_tracking: UsageTracking {
                    per_user_tracking: true,
                    per_project_tracking: true,
                    reporting_interval: 3600.0,             // 1 hour
                    retention_period: 3600.0 * 24.0 * 30.0, // 30 days
                },
            },
            job_registry: HashMap::new(),
        }
    }

    /// Add a backend to the distributed executor
    pub fn add_backend(&mut self, backend: ExecutionBackend) -> QuantRS2Result<()> {
        // Validate backend configuration
        if backend.id.is_empty() {
            return Err(QuantRS2Error::InvalidInput(
                "Backend ID cannot be empty".to_string(),
            ));
        }

        // Check for duplicate IDs
        if self.backends.iter().any(|b| b.id == backend.id) {
            return Err(QuantRS2Error::InvalidInput(format!(
                "Backend with ID '{}' already exists",
                backend.id
            )));
        }

        // Update resource pool
        self.resource_manager.resource_pool.total_qubits += backend.performance.max_qubits;
        self.resource_manager.resource_pool.available_slots += 1;

        self.backends.push(backend);
        Ok(())
    }

    /// Submit a job for distributed execution
    pub fn submit_job<const N: usize>(&mut self, job: DistributedJob<N>) -> QuantRS2Result<String> {
        // Validate job
        if job.circuit.num_gates() == 0 {
            return Err(QuantRS2Error::InvalidInput(
                "Cannot submit empty circuit".to_string(),
            ));
        }

        // Check resource requirements
        let required_qubits = job.circuit.num_qubits();
        if required_qubits > self.resource_manager.resource_pool.total_qubits {
            return Err(QuantRS2Error::UnsupportedQubits(
                required_qubits,
                format!(
                    "Maximum available qubits: {}",
                    self.resource_manager.resource_pool.total_qubits
                ),
            ));
        }

        // Select appropriate backends
        let selected_backends = self.select_backends(&job)?;
        if selected_backends.is_empty() {
            return Err(QuantRS2Error::BackendExecutionFailed(
                "No suitable backends available".to_string(),
            ));
        }

        let job_id = job.id.clone();
        let submitted_at = job.submitted_at;

        // Register the job as queued and track the selected backends
        self.job_registry.insert(
            job_id.clone(),
            JobRecord {
                status: ExecutionStatus::Queued,
                backends: selected_backends,
                submitted_at,
            },
        );

        Ok(job_id)
    }

    /// Select appropriate backends for a job
    fn select_backends<const N: usize>(
        &self,
        job: &DistributedJob<N>,
    ) -> QuantRS2Result<Vec<String>> {
        let mut suitable_backends = Vec::new();

        for backend in &self.backends {
            if self.is_backend_suitable(backend, job) {
                suitable_backends.push(backend.id.clone());
            }
        }

        // Apply load balancing strategy
        match self.load_balancer.strategy {
            LoadBalancingStrategy::RoundRobin => {
                // Simple round-robin selection
                suitable_backends.truncate(self.fault_tolerance.redundancy_level.max(1));
            }
            LoadBalancingStrategy::LeastQueueTime => {
                // Sort by queue time; entries without a matching backend retain
                // their relative order (treated as having zero wait time).
                suitable_backends.sort_by(|a, b| {
                    let wait_a = self
                        .backends
                        .iter()
                        .find(|backend| backend.id == *a)
                        .map(|backend| backend.queue_info.estimated_wait_time)
                        .unwrap_or(0.0);
                    let wait_b = self
                        .backends
                        .iter()
                        .find(|backend| backend.id == *b)
                        .map(|backend| backend.queue_info.estimated_wait_time)
                        .unwrap_or(0.0);
                    wait_a
                        .partial_cmp(&wait_b)
                        .unwrap_or(std::cmp::Ordering::Equal)
                });
                suitable_backends.truncate(self.fault_tolerance.redundancy_level.max(1));
            }
            _ => {
                // Default to first available
                suitable_backends.truncate(1);
            }
        }

        Ok(suitable_backends)
    }

    /// Check if a backend is suitable for a job
    fn is_backend_suitable<const N: usize>(
        &self,
        backend: &ExecutionBackend,
        job: &DistributedJob<N>,
    ) -> bool {
        // Check status
        if backend.status != BackendStatus::Available {
            return false;
        }

        // Check qubit requirements
        if job.circuit.num_qubits() > backend.performance.max_qubits {
            return false;
        }

        // Check circuit depth
        if job.circuit.num_gates() > backend.performance.max_depth {
            return false;
        }

        // Check target backends (if specified)
        if let Some(ref targets) = job.target_backends {
            if !targets.contains(&backend.id) {
                return false;
            }
        }

        // Check queue capacity
        if backend.queue_info.queue_length >= backend.queue_info.max_queue_size {
            return false;
        }

        true
    }

    /// Get the current execution status for a previously submitted job.
    ///
    /// Returns `QuantRS2Error::InvalidInput` if no job with the given ID exists.
    pub fn get_job_status(&self, job_id: &str) -> QuantRS2Result<ExecutionStatus> {
        self.job_registry
            .get(job_id)
            .map(|record| record.status.clone())
            .ok_or_else(|| QuantRS2Error::InvalidInput(format!("Unknown job ID: '{job_id}'")))
    }

    /// Cancel a queued or running job.
    ///
    /// If the job is already completed, failed, or cancelled the call succeeds
    /// but the status is not changed.  Returns `QuantRS2Error::InvalidInput`
    /// if no job with the given ID exists.
    pub fn cancel_job(&mut self, job_id: &str) -> QuantRS2Result<()> {
        let record = self
            .job_registry
            .get_mut(job_id)
            .ok_or_else(|| QuantRS2Error::InvalidInput(format!("Unknown job ID: '{job_id}'")))?;

        match record.status {
            ExecutionStatus::Queued | ExecutionStatus::Running => {
                record.status = ExecutionStatus::Cancelled;
            }
            // Already in a terminal state — nothing to do
            ExecutionStatus::Completed
            | ExecutionStatus::Failed(_)
            | ExecutionStatus::Cancelled
            | ExecutionStatus::TimedOut => {}
        }

        Ok(())
    }

    /// Retrieve the result record for a job.
    ///
    /// Returns `QuantRS2Error::InvalidInput` if no job with the given ID exists.
    /// For jobs that are still queued or running the returned `status` field
    /// will reflect that; callers should check the status before consuming the
    /// result fields.
    pub fn get_results(&self, job_id: &str) -> QuantRS2Result<DistributedResult> {
        let record = self
            .job_registry
            .get(job_id)
            .ok_or_else(|| QuantRS2Error::InvalidInput(format!("Unknown job ID: '{job_id}'")))?;

        let elapsed = record.submitted_at.elapsed();

        Ok(DistributedResult {
            job_id: job_id.to_string(),
            status: record.status.clone(),
            backend_results: HashMap::new(),
            final_result: None,
            metadata: ExecutionMetadata {
                total_time: elapsed,
                queue_time: Duration::from_secs(0),
                backends_used: record.backends.clone(),
                resource_usage: ResourceUsage {
                    cpu_hours: elapsed.as_secs_f64() / 3600.0,
                    memory_hours: elapsed.as_secs_f64() / 3600.0,
                    qubit_hours: elapsed.as_secs_f64() / 3600.0,
                    network_usage: 0.0,
                },
                cost_info: None,
            },
        })
    }

    /// Get system health status
    #[must_use]
    pub fn get_health_status(&self) -> SystemHealthStatus {
        let available_backends = self
            .backends
            .iter()
            .filter(|b| b.status == BackendStatus::Available)
            .count();

        let total_qubits = self
            .backends
            .iter()
            .filter(|b| b.status == BackendStatus::Available)
            .map(|b| b.performance.max_qubits)
            .sum();

        SystemHealthStatus {
            total_backends: self.backends.len(),
            available_backends,
            total_qubits,
            average_queue_time: self
                .backends
                .iter()
                .map(|b| b.queue_info.estimated_wait_time)
                .sum::<f64>()
                / self.backends.len() as f64,
            system_load: self.calculate_system_load(),
        }
    }

    /// Calculate overall system load
    fn calculate_system_load(&self) -> f64 {
        if self.backends.is_empty() {
            return 0.0;
        }

        let total_capacity: f64 = self
            .backends
            .iter()
            .map(|b| b.queue_info.max_queue_size as f64)
            .sum();

        let current_load: f64 = self
            .backends
            .iter()
            .map(|b| b.queue_info.queue_length as f64)
            .sum();

        if total_capacity > 0.0 {
            current_load / total_capacity
        } else {
            0.0
        }
    }
}

/// System health status
#[derive(Debug, Clone)]
pub struct SystemHealthStatus {
    /// Total number of backends
    pub total_backends: usize,
    /// Number of available backends
    pub available_backends: usize,
    /// Total available qubits
    pub total_qubits: usize,
    /// Average queue time across all backends
    pub average_queue_time: f64,
    /// Overall system load (0.0 to 1.0)
    pub system_load: f64,
}

impl Default for DistributedExecutor {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_distributed_executor_creation() {
        let executor = DistributedExecutor::new();
        assert_eq!(executor.backends.len(), 0);
        assert_eq!(executor.resource_manager.resource_pool.total_qubits, 0);
    }

    #[test]
    fn test_backend_addition() {
        let mut executor = DistributedExecutor::new();

        let backend = ExecutionBackend {
            id: "test_backend".to_string(),
            backend_type: BackendType::Simulator {
                simulator_type: SimulatorType::StateVector,
                host: "localhost".to_string(),
            },
            status: BackendStatus::Available,
            performance: BackendPerformance {
                max_qubits: 10,
                max_depth: 1000,
                gate_fidelities: HashMap::new(),
                coherence_times: HashMap::new(),
                execution_time_model: ExecutionTimeModel {
                    base_time: 0.1,
                    time_per_gate: 0.001,
                    time_per_qubit: 0.01,
                    time_per_measurement: 0.005,
                    network_latency: 0.05,
                },
                throughput: 10.0,
            },
            queue_info: QueueInfo {
                queue_length: 0,
                estimated_wait_time: 0.0,
                max_queue_size: 100,
                priority_levels: vec![Priority::Normal, Priority::High],
            },
            capabilities: BackendCapabilities {
                supported_gates: vec!["h".to_string(), "cnot".to_string()],
                mid_circuit_measurements: false,
                classical_control: false,
                reset_operations: false,
                connectivity: ConnectivityGraph {
                    num_qubits: 10,
                    edges: vec![(0, 1), (1, 2)],
                    topology: TopologyType::Linear,
                },
                noise_model: None,
            },
            network_config: NetworkConfig {
                endpoint: "http://localhost:8080".to_string(),
                credentials: Credentials {
                    auth_type: AuthenticationType::None,
                    api_key: None,
                    token: None,
                    username_password: None,
                },
                timeouts: TimeoutConfig {
                    connection_timeout: 5.0,
                    request_timeout: 30.0,
                    total_timeout: 60.0,
                },
                retry_policy: RetryPolicy {
                    max_retries: 3,
                    base_delay: 1.0,
                    backoff_strategy: BackoffStrategy::Exponential { multiplier: 2.0 },
                    retryable_errors: vec![ErrorType::NetworkError, ErrorType::TimeoutError],
                },
            },
        };

        executor
            .add_backend(backend)
            .expect("Failed to add backend to executor");
        assert_eq!(executor.backends.len(), 1);
        assert_eq!(executor.resource_manager.resource_pool.total_qubits, 10);
    }

    #[test]
    fn test_job_submission() {
        let mut executor = DistributedExecutor::new();

        // Add a backend first
        let backend = create_test_backend();
        executor
            .add_backend(backend)
            .expect("Failed to add backend to executor");

        // Create a test job
        let mut circuit = Circuit::<2>::new();
        circuit.h(QubitId(0)).expect("Failed to add Hadamard gate"); // Add a gate so it's not empty
        let job = DistributedJob {
            id: "test_job".to_string(),
            circuit,
            parameters: ExecutionParameters {
                shots: 1000,
                optimization_level: 1,
                error_mitigation: vec![],
                result_format: ResultFormat::Counts,
                memory_requirement: None,
            },
            priority: Priority::Normal,
            target_backends: None,
            submitted_at: Instant::now(),
            deadline: None,
        };

        let job_id = executor
            .submit_job(job)
            .expect("Failed to submit job to executor");
        assert_eq!(job_id, "test_job");
    }

    fn create_test_backend() -> ExecutionBackend {
        ExecutionBackend {
            id: "test_backend".to_string(),
            backend_type: BackendType::Simulator {
                simulator_type: SimulatorType::StateVector,
                host: "localhost".to_string(),
            },
            status: BackendStatus::Available,
            performance: BackendPerformance {
                max_qubits: 10,
                max_depth: 1000,
                gate_fidelities: HashMap::new(),
                coherence_times: HashMap::new(),
                execution_time_model: ExecutionTimeModel {
                    base_time: 0.1,
                    time_per_gate: 0.001,
                    time_per_qubit: 0.01,
                    time_per_measurement: 0.005,
                    network_latency: 0.05,
                },
                throughput: 10.0,
            },
            queue_info: QueueInfo {
                queue_length: 0,
                estimated_wait_time: 0.0,
                max_queue_size: 100,
                priority_levels: vec![Priority::Normal, Priority::High],
            },
            capabilities: BackendCapabilities {
                supported_gates: vec!["h".to_string(), "cnot".to_string()],
                mid_circuit_measurements: false,
                classical_control: false,
                reset_operations: false,
                connectivity: ConnectivityGraph {
                    num_qubits: 10,
                    edges: vec![(0, 1), (1, 2)],
                    topology: TopologyType::Linear,
                },
                noise_model: None,
            },
            network_config: NetworkConfig {
                endpoint: "http://localhost:8080".to_string(),
                credentials: Credentials {
                    auth_type: AuthenticationType::None,
                    api_key: None,
                    token: None,
                    username_password: None,
                },
                timeouts: TimeoutConfig {
                    connection_timeout: 5.0,
                    request_timeout: 30.0,
                    total_timeout: 60.0,
                },
                retry_policy: RetryPolicy {
                    max_retries: 3,
                    base_delay: 1.0,
                    backoff_strategy: BackoffStrategy::Exponential { multiplier: 2.0 },
                    retryable_errors: vec![ErrorType::NetworkError, ErrorType::TimeoutError],
                },
            },
        }
    }
}