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

// 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 msg -> 
    printfn "Error: %s" msg

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

🧭 Intent-First Algorithms (Why Some Algorithms Behave Differently Per Backend)

Some algorithms in this library are implemented as intent → plan → execute rather than as a fixed “gate circuit”. This allows the same algorithm to run correctly on:

This is mostly transparent to users: you call the same API, but the backend may choose a different execution strategy. See docs/adr-intent-first-algorithms.md.

💻 Cross-Language Support

🎯 Problem Types & Examples

Graph Coloring

open FSharp.Azure.Quantum

// Register allocation for compiler optimization
let problem = graphColoring {
    node "Task1" ["Task2"; "Task3"]
    node "Task2" ["Task1"; "Task4"]
    node "Task3" ["Task1"; "Task4"]
    node "Task4" ["Task2"; "Task3"]
    colors ["Slot A"; "Slot B"; "Slot C"]
    objective MinimizeColors
}

match GraphColoring.solve problem 3 None with
| Ok solution ->
    printfn "Valid coloring: %b" solution.IsValid
    printfn "Colors used: %d/%d" solution.ColorsUsed 3
    printfn "Conflicts: %d" solution.ConflictCount
| Error msg -> printfn "Error: %s" msg

MaxCut

let vertices = ["A"; "B"; "C"; "D"]
let edges = [
    ("A", "B", 1.0)
    ("B", "C", 2.0)
    ("C", "D", 1.0)
    ("D", "A", 1.0)
]

let problem = MaxCut.createProblem vertices edges

match MaxCut.solve problem None with
| Ok solution ->
    printfn "Partition S: %A" solution.PartitionS
    printfn "Partition T: %A" solution.PartitionT
    printfn "Cut value: %.2f" solution.CutValue
| Error msg -> printfn "Error: %s" msg

Knapsack

let items = [
    ("laptop", 3.0, 1000.0)   // (id, weight, value)
    ("phone", 0.5, 500.0)
    ("tablet", 1.5, 700.0)
    ("monitor", 2.0, 600.0)
]

let problem = Knapsack.createProblem items 5.0  // capacity = 5.0

match Knapsack.solve problem None with
| Ok solution ->
    printfn "Total value: $%.2f" solution.TotalValue
    printfn "Total weight: %.2f/%.2f" solution.TotalWeight problem.Capacity
    printfn "Items: %A" (solution.SelectedItems |> List.map (fun i -> i.Id))
| Error msg -> printfn "Error: %s" msg

TSP

let cities = [
    ("Seattle", 0.0, 0.0)
    ("Portland", 1.0, 0.5)
    ("San Francisco", 2.0, 1.5)
    ("Los Angeles", 3.0, 3.0)
]

let problem = TSP.createProblem cities

match TSP.solve problem None with
| Ok tour ->
    printfn "Optimal route: %s" (String.concat " → " tour.Cities)
    printfn "Total distance: %.2f" tour.TotalDistance
| Error msg -> printfn "Error: %s" msg

Portfolio

let assets = [
    ("AAPL", 0.12, 0.15, 150.0)  // (symbol, return, risk, price)
    ("GOOGL", 0.10, 0.12, 2800.0)
    ("MSFT", 0.11, 0.14, 350.0)
]

let problem = Portfolio.createProblem assets 10000.0  // budget

match Portfolio.solve problem None with
| Ok allocation ->
    printfn "Portfolio value: $%.2f" allocation.TotalValue
    printfn "Expected return: %.2f%%" (allocation.ExpectedReturn * 100.0)
    printfn "Risk: %.2f" allocation.Risk
    
    allocation.Allocations 
    |> List.iter (fun (symbol, shares, value) ->
        printfn "  %s: %.2f shares ($%.2f)" symbol shares value)
| Error msg -> printfn "Error: %s" msg

Network Flow

let nodes = [
    NetworkFlow.SourceNode("Factory", 100)
    NetworkFlow.IntermediateNode("Warehouse", 80)
    NetworkFlow.SinkNode("Store1", 40)
    NetworkFlow.SinkNode("Store2", 60)
]

let routes = [
    NetworkFlow.Route("Factory", "Warehouse", 5.0)
    NetworkFlow.Route("Warehouse", "Store1", 3.0)
    NetworkFlow.Route("Warehouse", "Store2", 4.0)
]

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

match NetworkFlow.solve problem None with
| Ok flow ->
    printfn "Total cost: $%.2f" flow.TotalCost
    printfn "Fill rate: %.1f%%" (flow.FillRate * 100.0)
| Error msg -> printfn "Error: %s" msg

Task Scheduling

open FSharp.Azure.Quantum

// Define tasks 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"  // Dependency
    requires "Worker" 2.0
    deadline 180.0
}

let taskC = scheduledTask {
    taskId "TaskC"
    duration (minutes 30.0)
    after "TaskA"
    requires "Machine" 1.0
}

// Define resources
let worker = resource {
    resourceId "Worker"
    capacity 3.0
}

let machine = resource {
    resourceId "Machine"
    capacity 2.0
}

// Build scheduling problem
let problem = scheduling {
    tasks [taskA; taskB; taskC]
    resources [worker; machine]
    objective MinimizeMakespan
    timeHorizon 500.0
}

// Solve with quantum backend for resource constraints
let backend = BackendAbstraction.createLocalBackend()
match solveQuantum backend problem with
| Ok solution ->
    printfn "Makespan: %.2f hours" solution.Makespan
    solution.Schedule 
    |> List.iter (fun assignment ->
        printfn "%s: starts %.2f, ends %.2f" 
            assignment.TaskId assignment.StartTime assignment.EndTime)
| Error msg -> printfn "Error: %s" msg

🏗️ 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: %.2f" solution.CutValue
| Error msg -> printfn "Error: %s" msg

Characteristics:

Azure Quantum (Cloud)

open FSharp.Azure.Quantum.Backends.AzureQuantumWorkspace

// Create workspace
let workspace = createDefault "subscription-id" "resource-group" "workspace-name" "eastus"

// IonQ Backend (trapped-ion)
let backend_ionq = BackendAbstraction.createFromWorkspace workspace "ionq.simulator"

// Rigetti Backend (superconducting)
let backend_rigetti = BackendAbstraction.createFromWorkspace workspace "rigetti.sim.qvm"

// Atom Computing Backend (neutral atoms, 100+ qubits, all-to-all connectivity)
let backend_atom = BackendAbstraction.createFromWorkspace workspace "atom-computing.sim"

// Quantinuum Backend (trapped-ion, highest fidelity)
let backend_quantinuum = BackendAbstraction.createFromWorkspace workspace "quantinuum.sim.h1-1sc"

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

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