📖 Table of Contents

1. Quick Start - Start here! Get running in 5 minutes
2. Problem Builders - High-level APIs for 6 optimization problems
3. HybridSolver - Automatic classical/quantum routing
4. Architecture - How the library is organized
5. Error Mitigation - Reduce quantum noise by 30-90%
6. C# Interop - Using from C#
7. Backend Selection - Local vs Cloud quantum execution
8. Educational Algorithms - Grover, QFT, Amplitude Amplification (for learning)
9. Phase 2 Builders - Quantum Arithmetic, Cryptographic Analysis, Phase Estimation

🚀 Quick Start

Installation

F# Computation Expressions

C# Fluent API

What happens:

1. Computation expression builds graph coloring problem
2. GraphColoring.solve calls QuantumGraphColoringSolver internally
3. QAOA quantum algorithm encodes problem as QUBO
4. LocalBackend simulates quantum circuit (≤16 qubits)
5. Returns color assignments with validation

🎯 Problem Builders

1. Graph Coloring

Use Case: Register allocation, frequency assignment, exam scheduling

2. MaxCut

Use Case: Circuit design, community detection, load balancing

3. Knapsack (0/1)

Use Case: Resource allocation, portfolio selection, cargo loading

4. Traveling Salesperson Problem (TSP)

Use Case: Route optimization, delivery planning, logistics

5. Portfolio Optimization

Use Case: Investment allocation, asset selection, risk management

6. Network Flow

Use Case: Supply chain optimization, logistics, distribution planning

🤖 HybridSolver - Automatic Classical/Quantum Routing

Smart solver that automatically chooses between classical and quantum execution based on problem analysis.

The HybridSolver provides a unified API that:

• ✅ Analyzes problem size, structure, and complexity
• ✅ Estimates quantum advantage potential
• ✅ Routes to classical solver (fast, free) OR quantum backend (scalable, expensive)
• ✅ Provides reasoning for solver selection
• ✅ Optionally compares both methods for validation

Decision Framework:

• Small problems (< 50 variables) → Classical solver (milliseconds, $0)
• Large problems (> 100 variables) → Quantum solver (seconds-minutes, ~$10-100)
• Automatic cost guards and recommendations

Supported Problems

The HybridSolver supports all 5 main optimization problems:

Features

• ✅ Unified API: Single function call for any problem size
• ✅ Smart Routing: Automatic classical/quantum decision
• ✅ Cost Guards: MaxCostUSD prevents runaway quantum costs
• ✅ Validation Mode: EnableComparison = true runs both methods
• ✅ Transparent Reasoning: Explains why each method was chosen
• ✅ Quantum Advisor: Provides recommendations on quantum readiness

When to Use HybridSolver vs Direct Builders

Use HybridSolver when:

• Problem size varies (sometimes small, sometimes large)
• You want automatic cost optimization
• You need validation/comparison between classical and quantum
• You're prototyping and unsure which approach is better

Use Direct Builders when:

• You always want quantum (for research/learning)
• Problem size is consistently in quantum range (10-16 qubits)
• You need fine-grained control over backend configuration
• You're integrating with specific QAOA parameter tuning

Location: src/FSharp.Azure.Quantum/Solvers/Hybrid/HybridSolver.fs
Status: Production-ready - Recommended for production deployments

🏗️ Architecture

3-Layer Quantum-Only Architecture

Layer Responsibilities

Layer 1: High-Level Builders 🟢

Who uses it: End users (F# and C# developers)
Purpose: Business domain APIs with problem-specific validation

Features:

• ✅ F# computation expressions (graphColoring { })
• ✅ C# fluent APIs (CSharpBuilders.MaxCutProblem())
• ✅ Type-safe problem specification
• ✅ Domain-specific validation
• ✅ Automatic backend creation (defaults to LocalBackend)

Example:

Layer 2: Quantum Solvers 🟠

Who uses it: High-level builders (internal delegation)
Purpose: QAOA implementations for specific problem types

Features:

• ✅ Problem → QUBO encoding
• ✅ QAOA circuit construction
• ✅ Variational parameter optimization (Nelder-Mead)
• ✅ Solution decoding and validation
• ✅ Backend-agnostic (accepts IQuantumBackend)

Example:

Layer 3: Quantum Backends 🔵

Who uses it: Quantum solvers
Purpose: Quantum circuit execution

Backend Types:

Example:

LocalBackend Internal Architecture

How LocalBackend simulates quantum circuits:

Key Components:

1. StateVector Module 🟢

   • Stores quantum state as complex amplitude array
   • Size: 2^n complex numbers (n = number of qubits)
   • Example: 3 qubits = 8 amplitudes

2. Gate Module 🟡

   • Matrix representations of quantum gates
   • Applied via tensor products and matrix multiplication
   • Gates: H, CNOT, RX, RY, RZ, SWAP, CZ, etc.

3. Measurement Module 🟠

   • Computes probabilities from amplitudes: P(x) = |amplitude(x)|²
   • Samples bitstrings according to probability distribution
   • Returns histogram: {bitstring → count}

4. QAOA Integration 🟣

   • Cost layer: Problem-specific rotations (RZ gates)
   • Mixer layer: Standard X-rotations (RX gates)
   • Repeat for multiple QAOA layers (p-layers)

Performance:

• 1-6 qubits: Instant (< 10ms)
• 7-10 qubits: Fast (< 100ms)
• 11-14 qubits: Moderate (< 1s)
• 15-16 qubits: Slow (< 10s)
• 17+ qubits: ❌ Exceeds limit (exponential memory: 2^n)

💻 C# Interop

C# Fluent API

All problem builders have C#-friendly extensions:

See: C# Usage Guide for complete examples

🔌 Backend Selection

Automatic Local Simulation (Default)

What happens:

1. Builder creates LocalBackend() automatically
2. Simulates quantum circuit using state vectors
3. ≤16 qubits supported (larger problems fail with error)

Explicit Cloud Backend

Backend Comparison

🔄 OpenQASM 2.0 Support

Import and export quantum circuits to IBM Qiskit, Cirq, and other OpenQASM-compatible platforms.

Why OpenQASM?

OpenQASM (Open Quantum Assembly Language) is the industry-standard text format for quantum circuits:

• ✅ IBM Qiskit - Primary format (6.7k GitHub stars)
• ✅ Amazon Braket - Native support
• ✅ Google Cirq - Import/export compatibility
• ✅ Interoperability - Share circuits between platforms

Export Circuits to OpenQASM

F# API:

Output (bell_state.qasm):

Import Circuits from OpenQASM

F# API:

C# API

Supported Gates

All standard OpenQASM 2.0 gates supported:

Workflow: Qiskit → F# → IonQ

Full interoperability workflow:

Round-Trip Compatibility

Circuits are preserved through export/import:

Use Cases

1. Share algorithms - Export F# quantum algorithms to IBM Qiskit community
2. Import research - Load published Qiskit papers/benchmarks into F# for analysis
3. Multi-provider - Develop in F#, run on IBM Quantum, Amazon Braket, IonQ
4. Education - Students learn quantum with type-safe F#, export to standard format
5. Validation - Cross-check results between F# LocalBackend and IBM simulators

See: tests/OpenQasmIntegrationTests.fs for comprehensive examples

🛡️ Error Mitigation

Reduce quantum noise and improve result accuracy by 30-90% with production-ready error mitigation techniques.

Why Error Mitigation?

Quantum computers are noisy (NISQ era). Error mitigation improves results without requiring error-corrected qubits:

• Gate errors - Imperfect quantum gates introduce noise (~0.1-1% per gate)
• Decoherence - Qubits lose quantum information over time
• Readout errors - Measurement outcomes have ~1-5% error rate

Error mitigation achieves near-ideal results on noisy hardware - critical for real-world quantum advantage.

Available Techniques

1️⃣ Zero-Noise Extrapolation (ZNE)

Richardson extrapolation to estimate error-free result.

How it works:

1. Run circuit at different noise levels (1.0x, 1.5x, 2.0x)
2. Fit polynomial to noise vs. result
3. Extrapolate to zero noise (λ=0)

Performance:

• ✅ 30-50% error reduction
• ✅ 3x cost overhead (3 noise scaling levels)
• ✅ Works on any backend (IonQ, Rigetti, Local)

F# Example:

When to use:

• Medium-depth circuits (20-50 gates)
• Cost-constrained (3x affordable)
• Need 30-50% error reduction

2️⃣ Probabilistic Error Cancellation (PEC)

Quasi-probability decomposition with importance sampling.

How it works:

1. Decompose noisy gates into sum of ideal gates with quasi-probabilities (some negative!)
2. Sample circuits from quasi-probability distribution
3. Reweight samples to cancel noise

Performance:

• ✅ 2-3x accuracy improvement
• ⚠️ 10-100x cost overhead (Monte Carlo sampling)
• ✅ Powerful for high-accuracy requirements

F# Example:

When to use:

• High-accuracy requirements (research, benchmarking)
• Budget available for 10-100x overhead
• Need 2-3x accuracy improvement

3️⃣ Readout Error Mitigation (REM)

Confusion matrix calibration with matrix inversion.

How it works:

1. Calibration phase - Prepare all basis states (|00⟩, |01⟩, |10⟩, |11⟩), measure confusion matrix
2. Correction phase - Invert matrix, multiply by measured histogram
3. Result - Corrected histogram with confidence intervals

Performance:

• ✅ 50-90% readout error reduction
• ✅ ~0x runtime overhead (one-time calibration, then free!)
• ✅ Works on all backends

F# Example:

When to use:

• Shallow circuits (readout errors dominate)
• Cost-constrained (free after calibration)
• All quantum applications (always beneficial)

4️⃣ Automatic Strategy Selection

Let the library choose the best technique for your circuit.

F# Example:

Strategy selection logic:

• Shallow (depth < 20): Readout errors dominate → REM
• Medium (20-50): Gate errors significant → ZNE
• Deep (> 50): High gate errors → PEC or Combined (ZNE + REM)
• High accuracy: PEC (if budget allows)
• Cost-constrained: REM (free) or ZNE (3x)

Decision Matrix

Real-World Example: MaxCut with ZNE

Expected improvement: 30-50% better cut value on noisy hardware.

Testing & Validation

Error mitigation is production-ready with comprehensive testing:

• ✅ 534 test cases across all modules
• ✅ ZNE: 111 tests (Richardson extrapolation, noise scaling, goodness-of-fit)
• ✅ PEC: 222 tests (quasi-probability, Monte Carlo, integration)
• ✅ REM: 161 tests (calibration, matrix inversion, confidence intervals)
• ✅ Strategy: 40 tests (selection logic, cost estimation, fallbacks)

See: tests/FSharp.Azure.Quantum.Tests/*ErrorMitigation*.fs

Further Reading

• ZNE Paper: Digital zero-noise extrapolation for quantum error mitigation (arXiv:2005.10921)
• PEC Paper: Probabilistic error cancellation with sparse Pauli-Lindblad models (arXiv:2201.09866)
• REM Paper: Practical characterization of quantum devices without tomography (arXiv:2004.11281)
• Tutorial: Mitiq - Quantum Error Mitigation

🧪 QAOA Algorithm Internals

How Quantum Optimization Works

QAOA (Quantum Approximate Optimization Algorithm):

1. QUBO Encoding: Convert problem → Quadratic Unconstrained Binary Optimization

   Graph Coloring → Binary variables for node-color assignments MaxCut → Binary variables for partition membership

2. Circuit Construction: Build parameterized quantum circuit

   |0⟩^n → H^⊗n → [Cost Layer (γ)] → [Mixer Layer (β)] → Measure

3. Parameter Optimization: Find optimal (γ, β) using Nelder-Mead

   for iteration in 1..maxIterations do let cost = evaluateCost(gamma, beta) optimizer.Update(cost)

4. Solution Extraction: Decode measurement results → problem solution

   Bitstring "0101" → [R1→Red, R2→Blue, R3→Red, R4→Blue]

QAOA Configuration

📚 Documentation

• Getting Started Guide - Installation and first examples
• C# Usage Guide - Complete C# interop guide
• API Reference - Complete API documentation
• Architecture Overview - Deep dive into library design
• Backend Switching Guide - Local vs Cloud backends
• FAQ - Common questions and troubleshooting

📊 Problem Size Guidelines

Note: LocalBackend limited to 16 qubits. Larger problems require Azure Quantum backends.

🎯 Design Philosophy

Rule 1: Quantum-Only Library

FSharp.Azure.Quantum is a quantum-first library - NO classical algorithms.

Why?

• ✅ Clear identity: Purpose-built for quantum optimization
• ✅ No architectural confusion: Pure quantum algorithm library
• ✅ Complements classical libraries: Use together with classical solvers when needed
• ✅ Educational value: Learn quantum algorithms without classical fallbacks

What this means:

Clean API Layers

1. High-Level Builders: Business domain APIs (register allocation, portfolio optimization)
2. Quantum Solvers: QAOA implementations (algorithm experts)
3. Quantum Backends: Circuit execution (hardware abstraction)

No leaky abstractions - Each layer has clear responsibilities.

📚 Educational Algorithms

Note: The following algorithms are provided for quantum computing education and research. They are NOT optimization solvers and should not be used for production optimization tasks. For production optimization, use the Problem Builders or HybridSolver above.

In addition to the production-ready optimization solvers above, the library includes foundational quantum algorithms for education and research:

Grover's Search Algorithm

Quantum search algorithm for finding elements in unsorted databases.

Features:

• ✅ Automatic optimal iteration calculation
• ✅ Amplitude amplification for multiple solutions
• ✅ Direct LocalSimulator integration (no IBackend)
• ✅ Educational/research tool (not production optimizer)

Location: src/FSharp.Azure.Quantum/Algorithms/
Status: Experimental - Research and education purposes

Note: Grover's algorithm is a standalone quantum search primitive, separate from the QAOA-based optimization builders. It does not use the IBackend abstraction and is optimized for specific search problems rather than general combinatorial optimization.

Amplitude Amplification

Generalization of Grover's algorithm for custom initial states.

Amplitude amplification extends Grover's algorithm to work with arbitrary initial state preparations (not just uniform superposition). This enables quantum speedups for problems beyond simple database search.

Key Insight: Grover's algorithm is a special case where:

• Initial state = uniform superposition H^⊗n|0⟩
• Reflection operator = Grover diffusion operator

Amplitude amplification allows:

• Custom initial state preparation A|0⟩
• Reflection about A|0⟩ (automatically generated)

Example:

Features:

• ✅ Custom state preparation (W-states, partial superpositions, arbitrary states)
• ✅ Cloud backend execution (IonQ, Rigetti, LocalBackend)
• ✅ Automatic reflection operator generation (circuit-based A†)
• ✅ Grover equivalence verification (shows Grover as special case)
• ✅ Optimal iteration calculation for arbitrary initial success probability
• ✅ Measurement-based results (histogram of basis states)

Backend Limitations:

• ⚠️ Backend execution returns measurement statistics only (not full amplitudes)
• ⚠️ Quantum phases are lost during measurement (fundamental limitation)
• ✅ Suitable for algorithms that measure amplification results
• ✅ For amplitude/phase analysis, use local simulation

Use Cases:

• Quantum walk algorithms with non-uniform initial distributions
• Fixed-point search (where initial state biases toward solutions)
• Quantum sampling with amplification
• Fixed-amplitude search (building block for quantum counting)

Location: Algorithms/AmplitudeAmplificationAdapter.fs

Status: Production-ready

Quantum Fourier Transform (QFT)

Quantum analog of the discrete Fourier transform - foundational building block for many quantum algorithms.

The QFT transforms computational basis states into frequency basis with exponential speedup over classical FFT:

• Classical FFT: O(n·2^n) operations
• Quantum QFT: O(n²) quantum gates

Mathematical Transform:

Example:

Features:

• ✅ O(n²) gate complexity (exponential speedup over classical)
• ✅ Cloud backend execution (IonQ, Rigetti, LocalBackend)
• ✅ Controlled phase gates (CP) with correct decomposition
• ✅ Bit-reversal SWAP gates (optional for QPE)
• ✅ Inverse QFT (QFT†) for result decoding
• ✅ Angle validation (prevents NaN/infinity)
• ✅ Measurement-based results (histogram of basis states)

Backend Limitations:

• ⚠️ Backend execution returns measurement statistics only (not full state vector)
• ⚠️ Amplitudes and phases are lost during measurement (fundamental quantum limitation)
• ✅ Suitable for algorithms that measure QFT output (Shor's, Phase Estimation)
• ✅ For amplitude/phase analysis, use local simulation

Use Cases:

• Shor's Algorithm: Integer factorization (period finding step)
• Quantum Phase Estimation: Eigenvalue estimation for VQE improvements
• Period Finding: Hidden subgroup problems
• Quantum Signal Processing: Frequency domain analysis

Performance:

• 3 qubits: 12 gates (3 H + 6 CPhase + 1 SWAP)
• 5 qubits: 27 gates (5 H + 20 CPhase + 2 SWAP)
• 10 qubits: 105 gates (10 H + 90 CPhase + 5 SWAP)

Location: Algorithms/QFTBackendAdapter.fs

Status: Production-ready

Phase 2 Builders: QFT-Based Quantum Applications

High-level builders for cryptography, quantum chemistry, and research applications.

The library provides three advanced builders that wrap QFT-based quantum algorithms for real-world business scenarios:

1. Quantum Arithmetic Builder

Use Case: Cryptographic operations, RSA encryption, modular arithmetic

C# API:

Business Applications:

• Cryptographic algorithm prototyping
• Educational RSA demonstrations
• Quantum arithmetic research

Example: examples/QuantumArithmetic/

2. Cryptographic Analysis Builder (Shor's Algorithm)

Use Case: RSA security assessment, post-quantum cryptography planning

C# API:

Business Applications:

• Security consulting (quantum threat assessment)
• Post-quantum cryptography migration planning
• Cryptanalysis research and education

Example: examples/CryptographicAnalysis/

3. Phase Estimation Builder (Quantum Chemistry)

Use Case: Drug discovery, molecular simulation, materials science

C# API:

Business Applications:

• Pharmaceutical drug discovery (binding energy)
• Materials science (electronic properties)
• Quantum chemistry simulations

Example: examples/PhaseEstimation/

Phase 2 Builder Features:

• ✅ Business-focused APIs hiding quantum complexity
• ✅ F# computation expressions + C# fluent API
• ✅ Comprehensive examples with real-world scenarios
• ✅ Educational value for quantum algorithm learning
• ⚠️ NISQ limitations: Toy examples only (< 20 qubits)
• ⚠️ Requires fault-tolerant quantum computers for production use

Current Status: Educational/research focus - Demonstrates quantum algorithms but hardware insufficient for real-world applications (2024-2025)

Library Scope & Focus

Primary Focus: QAOA-Based Combinatorial Optimization

This library is designed for NISQ-era practical quantum advantage in optimization:

• ✅ 6 optimization problem builders (Graph Coloring, MaxCut, TSP, Knapsack, Portfolio, Network Flow)
• ✅ QAOA implementation with automatic parameter tuning
• ✅ Error mitigation for noisy hardware (ZNE, PEC, REM)
• ✅ Production-ready solvers with cloud backend integration

Secondary Focus: Quantum Algorithm Education & Research

The Algorithms/ directory contains foundational quantum algorithms for learning:

• ✅ Grover's Search (quantum search, O(√N) speedup)
• ✅ Amplitude Amplification (generalization of Grover)
• ✅ Quantum Fourier Transform (O(n²) vs O(n·2^n) classical FFT)

Why F# for Quantum?

• Type-safe quantum circuit construction
• Functional programming matches quantum mathematics
• Interop with .NET ecosystem (C#, Azure, ML.NET)
• Higher level abstraction than Python (Qiskit) and Q#

🤝 Contributing

Contributions welcome!

Development principles:

• Maintain quantum-only architecture (no classical algorithms)
• Follow F# coding conventions
• Provide C# interop for new builders
• Include comprehensive tests
• Document QAOA encodings for new problem types

📄 License

Unlicense - Public domain. Use freely for any purpose.

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Examples: examples/

Status: Production Ready - Quantum-only architecture, 6 problem builders, full QAOA implementation