FSharp.Azure.Quantum

Quantum-First F# Library - Solve combinatorial optimization problems using QAOA (Quantum Approximate Optimization Algorithm) with automatic backend selection.

NuGet License

🚀 Quick Start

F# Computation Expressions

open FSharp.Azure.Quantum
open FSharp.Azure.Quantum.GraphColoring

// Graph Coloring: Register Allocation
let problem = graphColoring {
    node "R1" ["R2"; "R3"]
    node "R2" ["R1"; "R4"]
    node "R3" ["R1"; "R4"]
    node "R4" ["R2"; "R3"]
    colors ["EAX"; "EBX"; "ECX"; "EDX"]
}

// Solve using quantum optimization (QAOA)
match GraphColoring.solve problem 4 None with
| Ok solution ->
    printfn "Colors used: %d" solution.ColorsUsed
    solution.Assignments 
    |> Map.iter (fun node color -> printfn "%s → %s" node color)
| Error err -> 
    printfn "Error: %s" err.Message

C# Fluent API

using FSharp.Azure.Quantum;
using static FSharp.Azure.Quantum.CSharpBuilders;

// MaxCut: Circuit Partitioning
var vertices = new[] { "A", "B", "C", "D" };
var edges = new[] {
    (source: "A", target: "B", weight: 1.0),
    (source: "B", target: "C", weight: 2.0),
    (source: "C", target: "D", weight: 1.0),
    (source: "D", target: "A", weight: 1.0)
};

var problem = MaxCutProblem(vertices, edges);
var result = MaxCut.solve(problem, null);

if (result.IsOk) {
    var solution = result.ResultValue;
    Console.WriteLine($"Cut Value: {solution.CutValue}");
    Console.WriteLine($"Partition S: {string.Join(", ", solution.PartitionS)}");
    Console.WriteLine($"Partition T: {string.Join(", ", solution.PartitionT)}");
}

📦 Installation

dotnet add package FSharp.Azure.Quantum

✨ Features

🎯 7 Quantum Optimization Builders

Production-ready quantum algorithms for common combinatorial problems:

  1. Graph Coloring - Register allocation, frequency assignment, scheduling
  2. MaxCut - Circuit partitioning, community detection, load balancing
  3. Knapsack - Resource allocation, cargo loading, project selection
  4. TSP - Route optimization, delivery planning, logistics
  5. Portfolio - Investment allocation, asset selection, risk management
  6. Network Flow - Supply chain optimization, distribution planning
  7. Task Scheduling - Manufacturing workflows, project management, resource allocation with dependencies

🧠 Quantum Machine Learning

Apply quantum computing to machine learning:

Examples: examples/QML/ (VQCExample, FeatureMapExample, VariationalFormExample)

📊 Business Problem Builders

High-level APIs for business applications:

Examples: examples/AutoML/, examples/AnomalyDetection/, examples/BinaryClassification/, examples/PredictiveModeling/

🤖 HybridSolver - Optional Smart Routing

Optional optimization layer for variable-sized problems:

Recommendation: Use direct quantum API (GraphColoring.solve, MaxCut.solve, etc.) for most cases. HybridSolver adds classical fallback optimization for very small problems.

See: Getting Started Guide for detailed examples and decision criteria

🔬 QAOA Implementation

Quantum Approximate Optimization Algorithm with:

Example: examples/QaoaParameterOptimizationExample.fsx

🖥️ Multiple Execution Backends

💻 Cross-Language Support

🎯 Problem Types & Examples

Graph Coloring

// Register allocation for compiler optimization
let registers = graphColoring {
    node "R1" ["R2"; "R3"; "R5"]
    node "R2" ["R1"; "R4"]
    node "R3" ["R1"; "R4"; "R5"]
    node "R4" ["R2"; "R3"]
    node "R5" ["R1"; "R3"]
    colors ["EAX"; "EBX"; "ECX"; "EDX"]
    objective MinimizeColors
}

MaxCut

// Network community detection
let vertices = ["User1"; "User2"; "User3"; "User4"]
let edges = [
    ("User1", "User2", 3.0)  // interaction strength
    ("User2", "User3", 5.0)
    ("User3", "User4", 2.0)
    ("User4", "User1", 4.0)
]

let problem = MaxCut.createProblem vertices edges
let solution = MaxCut.solve problem None

Knapsack

// Cargo loading optimization
let items = [
    ("Electronics", 50.0, 10000.0)
    ("Furniture", 200.0, 5000.0)
    ("Textiles", 30.0, 3000.0)
    ("Machinery", 150.0, 8000.0)
]

let problem = Knapsack.createProblem items 300.0  // 300kg capacity

TSP

// Delivery route optimization
let cities = [
    ("Warehouse", 0.0, 0.0)
    ("Store A", 5.0, 3.0)
    ("Store B", 2.0, 7.0)
    ("Store C", 8.0, 4.0)
]

let problem = TSP.createProblem cities

Portfolio

// Investment allocation
let assets = [
    ("Tech ETF", 0.15, 0.20, 100.0)    // return, risk, price
    ("Bonds", 0.05, 0.05, 50.0)
    ("Real Estate", 0.10, 0.12, 200.0)
]

let problem = Portfolio.createProblem assets 10000.0  // $10k budget

Network Flow

// Supply chain optimization
let nodes = [
    { NetworkFlow.Id = "Factory"; NodeType = NetworkFlow.Source; Capacity = 1000 }
    { NetworkFlow.Id = "Warehouse"; NodeType = NetworkFlow.Intermediate; Capacity = 800 }
    { NetworkFlow.Id = "Customer"; NodeType = NetworkFlow.Sink; Capacity = 500 }
]

let routes = [
    { NetworkFlow.From = "Factory"; To = "Warehouse"; Cost = 5.0 }
    { NetworkFlow.From = "Warehouse"; To = "Customer"; Cost = 3.0 }
]

let problem = { NetworkFlow.Nodes = nodes; Routes = routes }

Task Scheduling

// Manufacturing workflow with dependencies
let taskA = scheduledTask {
    taskId "TaskA"
    duration (hours 2.0)
    priority 10.0
}

let taskB = scheduledTask {
    taskId "TaskB"
    duration (hours 1.5)
    after "TaskA"  // Must wait for A
    requires "Worker" 2.0
    deadline 180.0
}

let problem = scheduling {
    tasks [taskA; taskB]
    objective MinimizeMakespan
}

// Solve with quantum backend for resource constraints
let backend = LocalBackendFactory.createUnified()
match solveQuantum backend problem with
| Ok solution ->
    printfn "Makespan: %.2f" solution.Makespan
| Error err -> printfn "Error: %s" err.Message

🏗️ Architecture

3-Layer Quantum-Only Design:

3-Layer Quantum Architecture

Design Philosophy:

📚 Complete Documentation

🚀 Getting Started

📖 Core Concepts

🔬 Advanced Topics

🎯 Problem-Specific API Guides

💡 Working Code Examples

View source code on GitHub:

Optimization Problems (QAOA)

Advanced Quantum Algorithms

Interactive Demonstrations

🎯 When to Use This Library

✅ Use FSharp.Azure.Quantum When:

🔄 Consider Classical Libraries When:

Best Practice:

🔧 Backend Selection Guide

LocalBackend (Default)

// Automatic: No backend parameter needed
match MaxCut.solve problem None with
| Ok solution -> printfn "Max cut value: %f" solution.CutValue
| Error err -> eprintfn "Error: %s" err.Message

Characteristics:

Azure Quantum (Cloud)

// Create cloud backend - IonQ (trapped-ion)
let backend_ionq = // Cloud backend requires Azure Quantum workspace configuration
// createIonQBackend(
    connectionString = "YOUR_CONNECTION_STRING",
    targetId = "ionq.simulator"  // or "ionq.qpu"
)

// Rigetti (superconducting)
let backend_rigetti = // Cloud backend requires Azure Quantum workspace configuration
// createRigettiBackend(
    connectionString = "YOUR_CONNECTION_STRING",
    targetId = "rigetti.sim.qvm"  // or "rigetti.qpu.*"
)

// Atom Computing (neutral atoms, 100+ qubits, all-to-all connectivity)
let backend_atom = // Cloud backend requires Azure Quantum workspace
// createAtomComputingBackend(
    connectionString = "YOUR_CONNECTION_STRING",
    targetId = "atom-computing.sim"  // or "atom-computing.qpu.phoenix"
)

// Quantinuum (trapped-ion, highest fidelity)
let backend_quantinuum = // Cloud backend requires Azure Quantum workspace
// createQuantinuumBackend(
    connectionString = "YOUR_CONNECTION_STRING",
    targetId = "quantinuum.sim.h1-1sc"  // or "quantinuum.qpu.*"
)

// Pass to solver
match MaxCut.solve problem (Some backend_atom) with
| Ok solution -> printfn "Max cut value: %f" solution.CutValue
| Error err -> eprintfn "Error: %s" err.Message

Backend Characteristics:

Backend Qubits Technology Best For
IonQ 29+ (sim), 11 (QPU) Trapped-ion General gate-based algorithms
Rigetti 40+ (sim), 80 (QPU) Superconducting Fast gate operations
Atom Computing 100+ (sim/QPU) Neutral atoms Large-scale problems, all-to-all connectivity
Quantinuum 20-32 (sim/QPU) Trapped-ion High-precision (99.9%+ fidelity)

Cost & Performance:

🤝 Contributing

Contributions welcome! See GitHub Repository for contribution guidelines.

Areas we’d love help with:

🔗 Links

📊 Performance Guidelines

Problem Type LocalBackend Cloud Required
Graph Coloring ≤20 nodes 25+ nodes
MaxCut ≤20 vertices 25+ vertices
Knapsack ≤20 items 25+ items
TSP ≤8 cities 10+ cities
Portfolio ≤20 assets 25+ assets
Network Flow ≤15 nodes 20+ nodes
Task Scheduling ≤15 tasks 20+ tasks

Note: LocalBackend supports up to 20 qubits. Larger problems require cloud backends.

📄 License

This project is licensed under the Unlicense - dedicated to the public domain.

Status: Production Ready - Quantum-only architecture with 7 problem builders

Last Updated: 2025-12-03