User Guide

This comprehensive user guide covers all features and functionality of the QKD Simulation Platform.

Getting Started

After completing the Quick Start Guide tutorial, you should be familiar with the basic workflow. This guide will explore all features in detail.

Platform Overview

The QKD Simulation Platform consists of three main components:

Web Frontend: Interactive user interface for network configuration and simulation
Backend API: FastAPI server that handles simulation requests
Simulation Engine: Python-based simulation core with protocol implementations

Interface Layout

The main interface is divided into several sections:

Protocol Selection

Protocol Configuration

The protocol selection area allows you to choose between three QKD protocols:

DPS-QKD (Differential Phase Shift): - Best for: High-speed applications, simple hardware - Key features: Phase difference encoding, Mach-Zehnder interferometer - Parameters: Standard QKD parameters only

COW-QKD (Coherent One-Way): - Best for: Security-critical applications, eavesdropping detection - Key features: Intensity modulation, monitoring pulses - Parameters: Additional COW-specific parameters

BB84-QKD (Bennett-Brassard 1984): - Best for: Research, education, maximum security - Key features: Four quantum states, two bases, information-theoretic security - Parameters: Standard QKD parameters only

Protocol-Specific Parameters

COW-QKD includes additional parameters not available in other protocols:

Monitor Pulse Ratio (0.0 - 1.0): - What it is: Fraction of pulses used for eavesdropping detection - Default: 0.1 (10%) - Effect: Higher values improve security but reduce key rate - Recommendation: 0.1 for most applications

Detection Threshold (Photons): - What it is: Minimum photon count for detection - Default: 0 (single photon detection) - Effect: Higher values reduce sensitivity but improve noise immunity - Recommendation: 0 for most applications

Extinction Ratio (dB): - What it is: Ratio between “on” and “off” states of intensity modulator - Default: 20 dB - Effect: Higher values improve contrast between states - Recommendation: 20-30 dB for practical systems

Bit Flip Error Probability (0.0 - 1.0): - What it is: Probability of bit errors in classical post-processing - Default: 0.05 (5%) - Effect: Higher values increase QBER - Recommendation: 0.01-0.05 for realistic systems

Network Builder

The network builder provides a visual interface for creating and configuring QKD networks.

Node Management

Adding Nodes: - Click the “Add Node” button to create a new node - Nodes are automatically numbered and positioned - You can add up to 50 nodes (practical limit)

Node Positioning: - Drag nodes to reposition them - Nodes snap to a grid for neat layouts - Position nodes logically (e.g., in a chain or star topology)

Node Selection: - Click on a node to select it - Selected node appears highlighted - Node parameters appear in the sidebar

Node Deletion: - Select a node and click “Remove Node” - All connected channels are also removed - Operation cannot be undone (use Undo button)

Node Parameters

Each node has configurable parameters:

Detector Efficiency (0.0 - 1.0): - What it is: Quantum efficiency of the photon detector - Default: 0.9 (90%) - Effect: Higher values increase key rate - Typical range: 0.7-0.95 for practical detectors

Dark Count Rate (scientific notation): - What it is: Rate of spurious detector clicks per nanosecond - Default: 1e-8 (10^-8 per ns) - Effect: Higher values increase QBER - Typical range: 1e-9 to 1e-7 per ns

Mu (Average Photon Number) (0.0 - 1.0): - What it is: Average number of photons per pulse - Default: 0.2 - Effect: Higher values increase key rate but also QBER - Optimal range: 0.1-0.5 for most protocols

Number of Pulses (integer): - What it is: Total number of pulses to generate - Default: 10,000 - Effect: Higher values improve statistics but increase simulation time - Recommendation: 1,000-100,000 for most simulations

Pulse Repetition Rate (ns) (float): - What it is: Time between pulses in nanoseconds - Default: 1.0 ns - Effect: Affects key rate calculation - Typical range: 0.1-10 ns

Channel Management

Creating Channels: - Click and drag from one node to another - A blue animated line appears between nodes - Channels are automatically numbered

Channel Selection: - Click on a channel line to select it - Selected channel appears highlighted - Channel parameters appear in the sidebar

Channel Deletion: - Select a channel and click “Remove Channel” - Operation cannot be undone (use Undo button)

Channel Parameters

Each channel has configurable parameters:

Fiber Length (km) (float): - What it is: Physical length of the optical fiber - Default: 10.0 km - Effect: Longer distances increase attenuation and QBER - Typical range: 1-100 km for QKD

Attenuation (dB/km) (float): - What it is: Fiber loss per kilometer - Default: 0.2 dB/km - Effect: Higher values increase photon loss - Typical range: 0.15-0.25 dB/km for standard fiber

Wavelength (nm) (integer): - What it is: Operating wavelength of the system - Default: 1550 nm - Effect: Affects fiber attenuation and detector efficiency - Common values: 850 nm, 1310 nm, 1550 nm

Fiber Type (dropdown): - Standard Single Mode: SMF-28, most common - Dispersion Shifted: Optimized for specific wavelengths - Non-Zero Dispersion Shifted: Enhanced for DWDM - Photonic Crystal: Advanced fiber with unique properties

Phase Flip Probability (0.0 - 1.0): - What it is: Probability of phase errors in the channel - Default: 0.05 (5%) - Effect: Higher values increase QBER - Typical range: 0.01-0.1 for realistic channels

Network Topologies

The platform supports various network topologies:

Point-to-Point: - Two nodes connected by a single channel - Simplest configuration for basic QKD analysis - Good for protocol comparison and parameter optimization

Linear Chain: - Multiple nodes connected in sequence - Useful for trusted relay networks - Each node acts as both sender and receiver

Star Topology: - Central node connected to multiple peripheral nodes - Useful for hub-and-spoke networks - Central node can act as trusted relay

Mesh Topology: - Multiple connections between nodes - Provides redundancy and multiple paths - Complex but robust network design

Custom Topologies: - Create any arbitrary network structure - Limited only by practical constraints - Useful for research and analysis

Network Operations

Undo/Redo: - Click the Undo button to revert the last operation - History is maintained for the current session - Useful for experimenting with different configurations

Network Validation: - The system automatically validates network configurations - Errors are displayed in the interface - Common issues include disconnected nodes or invalid parameters

Network Export/Import: - Save network configurations for later use - Share configurations with other users - Useful for reproducible research

Simulation Execution

Running Simulations

Starting a Simulation: 1. Configure protocol and parameters 2. Build and configure the network 3. Click “Run Simulation” button 4. Wait for results to appear

Simulation Progress: - Progress indicator shows simulation status - Time estimates for completion - Cancel option for long simulations

Simulation Results: - Results appear in the results section - Per-channel breakdown of performance - Summary statistics and analysis

Simulation Parameters

Global Parameters: - Applied to all nodes and channels - Can be overridden by individual settings - Useful for consistent parameter sets

Node-Specific Parameters: - Override global settings for specific nodes - Useful for heterogeneous networks - Allows realistic modeling of different hardware

Channel-Specific Parameters: - Override global settings for specific channels - Useful for different fiber types or distances - Allows detailed network modeling

Results Analysis

Understanding Results

QBER (Quantum Bit Error Rate): - Definition: Fraction of bits that differ between Alice and Bob - Calculation: Number of errors / Number of compared bits - Good range: 3-11% for practical QKD systems - Interpretation: Lower is better, indicates channel quality

Sifted Key Length: - Definition: Number of bits after sifting process - Process: Alice and Bob publicly compare to establish shared bits - Efficiency: Protocol-dependent (25-50% of raw bits) - Interpretation: Higher is better, indicates protocol efficiency

Final Key Length: - Definition: Number of secure bits after post-processing - Process: Error correction and privacy amplification - Reduction: Typically 80-95% of sifted key - Interpretation: Final secure key available for use

Secure Key Rate (bps): - Definition: Rate of secure key generation in bits per second - Calculation: Final key length / Total simulation time - Units: Bits per second (bps) - Interpretation: Higher is better, indicates system performance

Theory Compliance: - Definition: Verification that results are within theoretical bounds - Check: QBER within acceptable range for the protocol - Status: ✅ (compliant) or ❌ (non-compliant) - Interpretation: Indicates simulation validity

Per-Channel Results

Channel Identification: - Each channel is numbered and labeled - Shows source and destination nodes - Protocol used for the channel

Performance Metrics: - QBER for each channel - Key generation statistics - Error analysis and breakdown

Parameter Summary: - Node parameters for source and destination - Channel parameters and configuration - Protocol-specific parameters

Theory Analysis: - Compliance with theoretical predictions - Warnings for non-compliant results - Recommendations for improvement

Advanced Features

Multi-Protocol Networks

Protocol Selection: - Different protocols can be used on different channels - Useful for protocol comparison studies - Allows heterogeneous network analysis

Protocol Parameters: - Each protocol maintains its own parameter set - Parameters are preserved when switching protocols - Useful for comparative analysis

Results Comparison: - Compare performance across protocols - Identify optimal protocols for different scenarios - Analyze protocol trade-offs

Trusted Relay Networks

Relay Configuration: - Add intermediate nodes as trusted relays - Configure relay parameters and behavior - Model realistic network topologies

End-to-End Key Generation: - Calculate secure key through multiple hops - Account for relay overhead and delays - Analyze network scalability

Security Considerations: - Trusted relay security model - Key management and distribution - Network security analysis

Parameter Optimization

Systematic Parameter Sweeps: - Vary parameters systematically - Identify optimal parameter combinations - Analyze parameter sensitivity

Performance Optimization: - Find maximum key rate configurations - Optimize for specific constraints - Balance performance and security

Sensitivity Analysis: - Analyze parameter impact on performance - Identify critical parameters - Understand system robustness

Data Export and Analysis

Results Export: - Export simulation results in various formats - Save data for external analysis - Share results with collaborators

Performance Plots: - Generate performance vs. parameter plots - Analyze trends and relationships - Visualize optimization results

Statistical Analysis: - Calculate confidence intervals - Analyze result variability - Perform statistical tests

Troubleshooting

Common Issues

Simulation Won’t Start: - Check network connectivity - Verify all parameters are valid - Ensure backend is running

High QBER (>11%): - Reduce fiber length - Check detector parameters - Verify photon number is reasonable - Check for parameter conflicts

Low Key Rate: - Increase photon number (but not too much) - Check detector efficiency - Verify pulse repetition rate - Check channel attenuation

No Results Displayed: - Check if nodes are properly connected - Verify all parameters are valid - Check browser console for errors - Ensure simulation completed successfully

Network Validation Errors: - Check for disconnected nodes - Verify parameter ranges - Ensure logical network structure - Check for parameter conflicts

Performance Optimization

Simulation Speed: - Reduce number of pulses for quick tests - Use fewer nodes for initial testing - Optimize parameter ranges - Use appropriate simulation parameters

Memory Usage: - Limit network size for large simulations - Use appropriate pulse counts - Monitor system resources - Optimize parameter storage

Accuracy vs. Speed: - Balance simulation accuracy with speed - Use appropriate parameter ranges - Consider statistical significance - Validate results with multiple runs

Best Practices

Simulation Design

Parameter Selection: - Use realistic parameter values - Consider hardware limitations - Account for practical constraints - Validate against theoretical bounds

Network Design: - Design logical network topologies - Consider practical constraints - Plan for scalability - Account for security requirements

Protocol Selection: - Choose appropriate protocols for your use case - Consider performance requirements - Account for security needs - Evaluate hardware requirements

Data Management

Result Organization: - Organize results systematically - Use consistent naming conventions - Document parameter sets - Maintain result history

Data Validation: - Verify result consistency - Check for outliers - Validate against theory - Cross-check with literature

Data Sharing: - Export results in standard formats - Document experimental conditions - Share parameter configurations - Maintain reproducibility

Research Workflows

Exploratory Analysis: - Start with simple configurations - Gradually increase complexity - Document parameter effects - Identify interesting regions

Systematic Studies: - Plan parameter sweeps carefully - Use appropriate statistical methods - Account for multiple comparisons - Validate results thoroughly

Comparative Analysis: - Use consistent parameter sets - Account for protocol differences - Consider practical constraints - Document comparison methodology

Advanced Topics

Custom Protocols

Protocol Implementation: - Extend the platform with new protocols - Implement custom sender/receiver classes - Add protocol-specific parameters - Integrate with analysis tools

Protocol Validation: - Validate against theoretical predictions - Compare with literature results - Test with known parameter sets - Verify security properties

Protocol Optimization: - Optimize protocol parameters - Analyze performance trade-offs - Identify optimal configurations - Consider practical constraints

Hardware Integration

Real Hardware: - Interface with real QKD hardware - Validate simulation models - Calibrate simulation parameters - Test with real-world conditions

Hardware Modeling: - Improve component models - Add realistic noise sources - Model hardware imperfections - Account for environmental effects

Performance Validation: - Compare simulation with hardware - Validate model accuracy - Identify model limitations - Improve simulation fidelity

Security Analysis

Attack Modeling: - Model various attack scenarios - Analyze security vulnerabilities - Evaluate countermeasures - Assess security margins

Security Metrics: - Calculate security parameters - Analyze key security - Evaluate privacy amplification - Assess information leakage

Security Optimization: - Optimize for security - Balance security and performance - Consider practical constraints - Evaluate security trade-offs

Future Enhancements

Planned Features

Additional Protocols: - More QKD protocol implementations - Hybrid protocol support - Protocol switching capabilities - Custom protocol framework

Advanced Analysis: - More sophisticated analysis tools - Statistical analysis packages - Machine learning integration - Automated optimization

User Interface: - Enhanced visualization tools - Real-time monitoring - Advanced network builder - Improved result display

Performance Improvements: - Faster simulation engine - Parallel processing support - GPU acceleration - Distributed computing

Getting Help

Documentation

User Documentation: - This user guide - API reference documentation - Example tutorials - Best practices guide

Developer Documentation: - Code documentation - Architecture guide - Contributing guidelines - Development setup

Research Documentation: - Protocol descriptions - Mathematical models - Validation studies - Performance analysis

Community Support

GitHub Issues: - Report bugs and problems - Request new features - Ask questions - Share experiences

Discussion Forum: - Community discussions - User support - Feature requests - Best practices sharing

Mailing List: - Announcements - Technical discussions - Community updates - Research collaboration

Contributing: - Code contributions - Documentation improvements - Bug reports - Feature suggestions

The QKD Simulation Platform is designed to be a comprehensive tool for QKD research, education, and development. This user guide covers the main features, but the platform is constantly evolving. Stay updated with the latest releases and contribute to the community to help improve the platform for everyone.