@smartnet360/svelte-components 0.0.102 → 0.0.103

package/dist/core/CoverageMap/core/CoverageCalculator.js

@@ -0,0 +1,375 @@
+/**
+ * Coverage Calculator - Main Orchestrator
+ *
+ * This is the main entry point for coverage calculations.
+ * It orchestrates all components and provides a clean API for:
+ * - Single sector coverage calculation
+ * - Multi-sector site coverage
+ * - Progress reporting
+ * - AI-ready result formatting
+ *
+ * Usage:
+ *   const calculator = new CoverageCalculator();
+ *   const result = await calculator.calculate(config, progressCallback);
+ *   // Result includes grid, statistics, and AI-ready summary
+ */
+import { calculateSingleSectorCoverage, calculateMultiSectorCoverage, extractMetrics } from './GridCalculator';
+// ============================================================================
+// COVERAGE CALCULATOR CLASS
+// ============================================================================
+/**
+ * Main Coverage Calculator
+ *
+ * Provides high-level API for coverage calculations with:
+ * - Configuration validation
+ * - Progress reporting
+ * - Error handling
+ * - Result formatting
+ * - AI-ready summaries
+ */
+export class CoverageCalculator {
+    /**
+     * Calculate coverage for a site configuration
+     *
+     * This is the main calculation method. It:
+     * 1. Validates configuration
+     * 2. Determines if single or multi-sector
+     * 3. Performs calculation
+     * 4. Generates statistics and summary
+     * 5. Formats result for consumption (including AI)
+     *
+     * @param config - Complete coverage configuration
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to complete coverage result
+     *
+     * @example
+     * const calculator = new CoverageCalculator();
+     * const result = await calculator.calculate({
+     *   site: siteConfig,
+     *   gridSettings: { cellSizeMeters: 50, maxRadiusKm: 10, ... },
+     *   signalThresholds: { excellent: -70, good: -85, ... },
+     *   calculateInterference: true
+     * }, (progress) => {
+     *   console.log(`Progress: ${progress.progress}% - ${progress.message}`);
+     * });
+     *
+     * // Access results
+     * console.log(`Coverage: ${result.grid.stats.coveragePercentage}%`);
+     * console.log(`Summary: ${result.summary.description}`);
+     * // Pass to AI for analysis
+     * const aiAnalysis = await analyzeWithAI(result);
+     */
+    async calculate(config, onProgress) {
+        const startTime = Date.now();
+        // Validate configuration
+        this.validateConfiguration(config);
+        // Determine calculation type
+        const enabledSectors = config.site.sectors.filter((s) => s.enabled);
+        let grid;
+        if (enabledSectors.length === 0) {
+            throw new Error('No enabled sectors in configuration');
+        }
+        else if (enabledSectors.length === 1) {
+            // Single sector calculation
+            onProgress?.({
+                stage: 'initializing',
+                progress: 0,
+                message: 'Starting single sector calculation...'
+            });
+            grid = calculateSingleSectorCoverage(enabledSectors[0], config.gridSettings, config.signalThresholds, onProgress);
+        }
+        else {
+            // Multi-sector calculation
+            onProgress?.({
+                stage: 'initializing',
+                progress: 0,
+                message: `Starting ${enabledSectors.length} sector calculation...`
+            });
+            grid = calculateMultiSectorCoverage(enabledSectors, config.gridSettings, config.signalThresholds, onProgress);
+        }
+        // Calculate total time
+        const calculationTimeMs = Date.now() - startTime;
+        // Generate AI-ready summary
+        const summary = this.generateSummary(config, grid, enabledSectors.length);
+        // Create final result
+        const result = {
+            config,
+            grid,
+            timestamp: new Date(),
+            calculationTimeMs,
+            summary
+        };
+        onProgress?.({
+            stage: 'complete',
+            progress: 100,
+            message: 'Coverage calculation complete!'
+        });
+        return result;
+    }
+    /**
+     * Validate configuration before calculation
+     *
+     * Checks for common configuration errors:
+     * - Invalid distances (negative, zero, too large)
+     * - Invalid frequencies (outside valid ranges)
+     * - Invalid antenna heights
+     * - Missing required data
+     *
+     * Throws descriptive errors if validation fails.
+     *
+     * @param config - Configuration to validate
+     * @throws Error if configuration is invalid
+     */
+    validateConfiguration(config) {
+        // Validate grid settings
+        const { cellSizeMeters, maxRadiusKm } = config.gridSettings;
+        if (cellSizeMeters <= 0 || cellSizeMeters > 1000) {
+            throw new Error(`Invalid cell size: ${cellSizeMeters}m. Must be between 1m and 1000m.`);
+        }
+        if (maxRadiusKm <= 0 || maxRadiusKm > 100) {
+            throw new Error(`Invalid max radius: ${maxRadiusKm}km. Must be between 0.1km and 100km.`);
+        }
+        // Check grid size doesn't exceed reasonable limits
+        const gridSize = (maxRadiusKm * 2000) / cellSizeMeters;
+        const totalCells = gridSize * gridSize;
+        if (totalCells > 1000000) {
+            // 1 million cells
+            throw new Error(`Grid too large: ${totalCells} cells. ` +
+                `Consider increasing cell size or decreasing radius. ` +
+                `Max recommended: 1 million cells.`);
+        }
+        // Validate sectors
+        if (!config.site.sectors || config.site.sectors.length === 0) {
+            throw new Error('Site configuration must include at least one sector');
+        }
+        for (const sector of config.site.sectors) {
+            // Validate frequency
+            if (sector.frequency < 100 || sector.frequency > 10000) {
+                throw new Error(`Invalid frequency for sector ${sector.sectorId}: ${sector.frequency}MHz. ` +
+                    `Must be between 100 MHz and 10 GHz.`);
+            }
+            // Validate TX power
+            if (sector.txPower < 0 || sector.txPower > 80) {
+                throw new Error(`Invalid TX power for sector ${sector.sectorId}: ${sector.txPower}dBm. ` +
+                    `Must be between 0 and 80 dBm.`);
+            }
+            // Validate antenna height
+            if (sector.position.height < 0 || sector.position.height > 500) {
+                throw new Error(`Invalid antenna height for sector ${sector.sectorId}: ${sector.position.height}m. ` +
+                    `Must be between 0 and 500 meters.`);
+            }
+            // Validate azimuth
+            if (sector.azimuth < 0 || sector.azimuth >= 360) {
+                throw new Error(`Invalid azimuth for sector ${sector.sectorId}: ${sector.azimuth}°. ` +
+                    `Must be between 0 and 359 degrees.`);
+            }
+            // Validate antenna pattern
+            if (!sector.antennaPattern) {
+                throw new Error(`Missing antenna pattern for sector ${sector.sectorId}`);
+            }
+            if (!sector.antennaPattern.pattern ||
+                sector.antennaPattern.pattern.length !== 360) {
+                throw new Error(`Invalid horizontal pattern for sector ${sector.sectorId}. ` +
+                    `Must have exactly 360 values.`);
+            }
+            if (!sector.antennaPattern.vertical_pattern ||
+                sector.antennaPattern.vertical_pattern.length !== 360) {
+                throw new Error(`Invalid vertical pattern for sector ${sector.sectorId}. ` +
+                    `Must have exactly 360 values.`);
+            }
+        }
+        // Validate thresholds
+        const { excellent, good, fair, edge } = config.signalThresholds;
+        if (excellent <= good || good <= fair || fair <= edge) {
+            throw new Error(`Invalid signal thresholds. Must be in descending order: ` +
+                `excellent (${excellent}) > good (${good}) > fair (${fair}) > edge (${edge})`);
+        }
+        if (excellent > -50 || edge < -120) {
+            throw new Error(`Signal thresholds out of reasonable range. ` +
+                `Excellent should be < -50 dBm, edge should be > -120 dBm.`);
+        }
+    }
+    /**
+     * Generate human-readable and AI-ready summary
+     *
+     * Creates a comprehensive summary of coverage results including:
+     * - Description: Human-readable text summary
+     * - Issues: List of detected problems/warnings
+     * - Metrics: Key numerical metrics for AI analysis
+     *
+     * This summary is designed to be consumed by:
+     * 1. Human users (description text)
+     * 2. UI components (structured data)
+     * 3. AI analysis tools (metrics + issues)
+     *
+     * @param config - Original configuration
+     * @param grid - Calculation results
+     * @param sectorCount - Number of sectors calculated
+     * @returns Summary object
+     */
+    generateSummary(config, grid, sectorCount) {
+        const stats = grid.stats;
+        const issues = [];
+        // Generate description
+        const description = this.createDescription(config, stats, sectorCount);
+        // Detect issues
+        this.detectIssues(config, stats, issues);
+        // Extract metrics for AI
+        const metrics = extractMetrics(grid);
+        return {
+            description,
+            issues,
+            metrics
+        };
+    }
+    /**
+     * Create human-readable description
+     */
+    createDescription(config, stats, sectorCount) {
+        const lines = [];
+        // Site info
+        lines.push(`Coverage Analysis for ${config.site.siteName}`);
+        lines.push(`Sectors: ${sectorCount}`);
+        lines.push('');
+        // Coverage summary
+        lines.push(`Total Coverage: ${stats.coveragePercentage.toFixed(1)}% of ${stats.totalAreaKm2.toFixed(2)} km²`);
+        lines.push('');
+        // Quality breakdown
+        lines.push('Signal Quality Distribution:');
+        lines.push(`  Excellent: ${stats.excellentAreaKm2.toFixed(2)} km² (${((stats.excellentAreaKm2 / stats.totalAreaKm2) * 100).toFixed(1)}%)`);
+        lines.push(`  Good: ${stats.goodAreaKm2.toFixed(2)} km² (${((stats.goodAreaKm2 / stats.totalAreaKm2) * 100).toFixed(1)}%)`);
+        lines.push(`  Fair: ${stats.fairAreaKm2.toFixed(2)} km² (${((stats.fairAreaKm2 / stats.totalAreaKm2) * 100).toFixed(1)}%)`);
+        lines.push(`  Poor: ${stats.poorAreaKm2.toFixed(2)} km² (${((stats.poorAreaKm2 / stats.totalAreaKm2) * 100).toFixed(1)}%)`);
+        lines.push('');
+        // Per-sector stats
+        if (stats.sectorStats) {
+            lines.push('Per-Sector Performance:');
+            // @ts-ignore - Object.entries returns unknown type
+            for (const [sectorId, sectorStat] of Object.entries(stats.sectorStats)) {
+                lines.push(`  ${sectorId}:`);
+                lines.push(`    Max Range: ${sectorStat.maxRangeKm.toFixed(2)} km`);
+                lines.push(`    Avg Signal: ${sectorStat.avgSignalDbm.toFixed(1)} dBm`);
+                lines.push(`    Coverage Area: ${sectorStat.coverageAreaKm2.toFixed(2)} km²`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Detect common issues and warnings
+     */
+    detectIssues(config, stats, issues) {
+        // Low coverage
+        if (stats.coveragePercentage < 50) {
+            issues.push(`Low overall coverage: ${stats.coveragePercentage.toFixed(1)}%. ` +
+                `Consider increasing TX power, antenna height, or optimizing azimuth/tilt.`);
+        }
+        // Poor quality dominance
+        const poorRatio = stats.poorAreaKm2 / stats.coveredAreaKm2;
+        if (poorRatio > 0.5) {
+            issues.push(`Over 50% of coverage is poor quality. ` +
+                `Consider increasing TX power or reducing coverage area with downtilt.`);
+        }
+        // Excessive range (potential interference)
+        if (stats.sectorStats) {
+            // @ts-ignore - Object.entries returns unknown type
+            for (const [sectorId, sectorStat] of Object.entries(stats.sectorStats)) {
+                if (sectorStat.maxRangeKm > 15) {
+                    issues.push(`Sector ${sectorId} has excessive range (${sectorStat.maxRangeKm.toFixed(1)} km). ` +
+                        `Consider adding downtilt to reduce interference to neighboring sites.`);
+                }
+            }
+        }
+        // Very short range (undershooting)
+        if (stats.sectorStats) {
+            // @ts-ignore - Object.entries returns unknown type
+            for (const [sectorId, sectorStat] of Object.entries(stats.sectorStats)) {
+                if (sectorStat.maxRangeKm < 1) {
+                    issues.push(`Sector ${sectorId} has very short range (${sectorStat.maxRangeKm.toFixed(1)} km). ` +
+                        `Check TX power, antenna height, and tilt settings.`);
+                }
+            }
+        }
+        // Weak average signal
+        if (stats.sectorStats) {
+            // @ts-ignore - Object.entries returns unknown type
+            for (const [sectorId, sectorStat] of Object.entries(stats.sectorStats)) {
+                if (sectorStat.avgSignalDbm < -90) {
+                    issues.push(`Sector ${sectorId} has weak average signal (${sectorStat.avgSignalDbm.toFixed(1)} dBm). ` +
+                        `Most coverage area is at poor signal levels.`);
+                }
+            }
+        }
+        // Minimal excellent coverage
+        const excellentRatio = stats.excellentAreaKm2 / stats.coveredAreaKm2;
+        if (excellentRatio < 0.1) {
+            issues.push(`Less than 10% of coverage is excellent quality. ` +
+                `Users will experience reduced data speeds in most areas.`);
+        }
+    }
+}
+// ============================================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================================
+/**
+ * Quick coverage calculation (simplified API)
+ *
+ * For simple use cases where you don't need full configuration control.
+ * Uses sensible defaults for most parameters.
+ *
+ * @param site - Site configuration
+ * @param options - Optional overrides
+ * @returns Coverage result
+ *
+ * @example
+ * const result = await quickCalculate(mySite, {
+ *   cellSizeMeters: 100,  // Faster calculation
+ *   maxRadiusKm: 5        // Smaller area
+ * });
+ */
+export async function quickCalculate(site, options) {
+    const calculator = new CoverageCalculator();
+    const config = {
+        site,
+        gridSettings: {
+            centerPosition: site.position,
+            cellSizeMeters: options?.cellSizeMeters || 50,
+            maxRadiusKm: options?.maxRadiusKm || 10,
+            pathLossModel: options?.pathLossModel || 'free-space'
+        },
+        signalThresholds: {
+            excellent: -70,
+            good: -85,
+            fair: -95,
+            edge: -105
+        },
+        calculateInterference: true
+    };
+    return calculator.calculate(config);
+}
+/**
+ * Calculate coverage and export for AI analysis
+ *
+ * Convenience function that calculates coverage and formats
+ * the result specifically for AI consumption.
+ *
+ * @param config - Coverage configuration
+ * @returns AI-ready analysis object
+ */
+export async function calculateForAI(config) {
+    const calculator = new CoverageCalculator();
+    const result = await calculator.calculate(config);
+    // Format for AI
+    return {
+        summary: result.summary.description,
+        metrics: result.summary.metrics,
+        issues: result.summary.issues,
+        sectorData: config.site.sectors.map((s) => ({
+            sectorId: s.sectorId,
+            azimuth: s.azimuth,
+            tilt: s.mechanicalTilt + s.electricalTilt,
+            power: s.txPower,
+            frequency: s.frequency,
+            stats: result.grid.stats.sectorStats[s.sectorId]
+        }))
+    };
+}

package/dist/core/CoverageMap/core/GridCalculator.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Grid Calculator
+ *
+ * This module implements grid-based coverage calculation.
+ * It divides the area around an antenna into a grid of cells
+ * and calculates signal strength at each cell center.
+ *
+ * Grid-based approach advantages:
+ * - Regular, predictable structure
+ * - Easy to visualize as heatmap
+ * - Efficient for large areas
+ * - Simple to parallelize (future enhancement)
+ *
+ * Process:
+ * 1. Create grid around antenna position
+ * 2. For each grid cell:
+ *    a. Calculate distance to antenna
+ *    b. Calculate bearing to antenna
+ *    c. Calculate path loss
+ *    d. Calculate antenna gain in direction
+ *    e. Calculate received signal strength
+ * 3. Aggregate results and generate statistics
+ */
+import type { Position2D, GridSettings, CoverageGrid, RFParameters, SectorConfig, SignalThresholds, ProgressCallback } from '../types';
+/**
+ * Generate grid structure
+ *
+ * Creates a 2D grid of geographic positions centered on a point.
+ * Grid cells are square (in meters), though they appear slightly
+ * rectangular on the map due to Earth's curvature.
+ *
+ * Grid sizing:
+ *   - Total size = 2 × maxRadius (covers circle)
+ *   - Number of cells = (2 × maxRadius) / cellSize in each dimension
+ *   - Example: 10 km radius, 50m cells → 400 × 400 = 160,000 cells
+ *
+ * Cell numbering:
+ *   - Rows increase North to South (row 0 = northernmost)
+ *   - Cols increase West to East (col 0 = westernmost)
+ *   - [row][col] indexing for 2D array
+ *
+ * Memory consideration:
+ *   - Each GridCell object: ~100 bytes
+ *   - 160,000 cells × 100 bytes = 16 MB
+ *   - Acceptable for modern browsers
+ *
+ * @param settings - Grid configuration
+ * @returns 2D array of positions (not yet populated with signal data)
+ */
+export declare function generateGridPositions(settings: GridSettings): Position2D[][];
+/**
+ * Calculate coverage grid for a single antenna/sector
+ *
+ * This is the core coverage calculation function. It:
+ * 1. Generates a grid of positions
+ * 2. For each position, calculates:
+ *    - Distance to antenna
+ *    - Path loss based on distance and model
+ *    - Signal strength based on antenna pattern
+ * 3. Classifies signal quality
+ * 4. Generates statistics
+ *
+ * Progress reporting:
+ *   - Calls progress callback after each row (or every N cells)
+ *   - Allows UI to show progress bar
+ *   - Keeps browser responsive for large grids
+ *
+ * Optimization notes:
+ *   - Path loss calculation is expensive (log operations)
+ *   - Could cache path loss vs distance (future optimization)
+ *   - Could use Web Workers for parallel calculation
+ *   - Current implementation: ~0.5ms per cell on modern CPU
+ *     (160,000 cells = ~80 seconds, acceptable for one-time calculation)
+ *
+ * @param rfParams - Complete RF configuration
+ * @param gridSettings - Grid size and resolution
+ * @param thresholds - Signal quality thresholds
+ * @param onProgress - Progress callback (optional)
+ * @returns Complete coverage grid with signal data
+ */
+export declare function calculateSingleSectorCoverage(rfParams: RFParameters, gridSettings: GridSettings, thresholds: SignalThresholds, onProgress?: ProgressCallback): CoverageGrid;
+/**
+ * Calculate coverage grid for multiple sectors
+ *
+ * Common scenario: Cell site with 3 sectors covering 360°.
+ * This function calculates signal from all sectors at each point
+ * and determines which sector provides strongest signal.
+ *
+ * Additional capabilities:
+ * - Identifies dominant server (which sector serves each location)
+ * - Calculates overlap areas (where multiple sectors are strong)
+ * - Detects potential interference zones
+ *
+ * Performance consideration:
+ *   - Calculates N × grid_size signal strengths (N = number of sectors)
+ *   - 3 sectors × 160,000 cells = 480,000 calculations
+ *   - Still manageable (few minutes on modern hardware)
+ *
+ * @param sectors - Array of sector configurations
+ * @param gridSettings - Grid size and resolution
+ * @param thresholds - Signal quality thresholds
+ * @param onProgress - Progress callback (optional)
+ * @returns Coverage grid with multi-sector data
+ */
+export declare function calculateMultiSectorCoverage(sectors: SectorConfig[], gridSettings: GridSettings, thresholds: SignalThresholds, onProgress?: ProgressCallback): CoverageGrid;
+/**
+ * Extract summary metrics for AI analysis
+ *
+ * Converts coverage grid into structured metrics suitable for
+ * AI interpretation and recommendation generation.
+ *
+ * @param grid - Coverage grid
+ * @returns Metrics object
+ */
+export declare function extractMetrics(grid: CoverageGrid): Record<string, number>;