FSharp.Azure.Quantum 0.1.0-alpha

FSharp.Azure.Quantum

F# library for quantum-inspired optimization - Solve TSP, Portfolio, and combinatorial optimization problems with automatic quantum vs classical routing.

🚀 Quick Start

open FSharp.Azure.Quantum.Classical

// Solve a TSP problem with named cities
let cities = [
    ("Seattle", 47.6, -122.3)
    ("Portland", 45.5, -122.7)
    ("San Francisco", 37.8, -122.4)
]

match TSP.solveDirectly cities None with
| Ok tour -> 
    printfn "Best route: %A" tour.Cities
    printfn "Distance: %.2f miles" tour.TotalDistance
| Error msg -> printfn "Error: %s" msg

📦 Installation

dotnet add package FSharp.Azure.Quantum --version 0.1.0-alpha

✨ Features

🔀 HybridSolver - Automatic Quantum/Classical Routing

Automatically chooses the best solver (quantum or classical) based on problem characteristics:

// Let the solver decide automatically
match HybridSolver.solveTsp distances None None None with
| Ok solution ->
    printfn "Method used: %A" solution.Method  // Classical or Quantum
    printfn "Reasoning: %s" solution.Reasoning
    printfn "Solution: %A" solution.Result
| Error msg -> printfn "Error: %s" msg

🗺️ TSP (Traveling Salesman Problem)

Solve routing problems with named cities:

let cities = [("NYC", 40.7, -74.0); ("LA", 34.0, -118.2); ("Chicago", 41.9, -87.6)]

// Option 1: Direct solve (easiest)
let tour = TSP.solveDirectly cities None

// Option 2: Build problem first (for customization)
let problem = TSP.createProblem cities
let tour = TSP.solve problem (Some customConfig)

Features:

• Named cities with coordinates
• Automatic distance calculation
• Simulated annealing with 2-opt
• Configurable iterations and cooling

💼 Portfolio Optimization

Optimize investment portfolios with risk/return constraints:

let assets = [
    ("AAPL", 0.12, 0.18, 150.0)  // symbol, return, risk, price
    ("MSFT", 0.10, 0.15, 300.0)
    ("GOOGL", 0.15, 0.20, 2800.0)
]

let allocation = Portfolio.solveDirectly assets 10000.0 None

match allocation with
| Ok result ->
    printfn "Total Value: $%.2f" result.TotalValue
    printfn "Expected Return: %.2f%%" (result.ExpectedReturn * 100.0)
    printfn "Risk: %.2f" result.Risk
| Error msg -> printfn "Error: %s" msg

Features:

• Greedy return/risk ratio optimization
• Budget constraints
• Min/max holding limits
• Efficient allocation

🤖 Quantum Advisor

Get recommendations on when to use quantum vs classical:

match QuantumAdvisor.getRecommendation distances with
| Ok recommendation ->
    printfn "Recommendation: %A" recommendation.RecommendationType
    printfn "Problem size: %d" recommendation.ProblemSize
    printfn "Reasoning: %s" recommendation.Reasoning
| Error msg -> printfn "Error: %s" msg

🧪 Classical Solvers

Direct access to classical optimization algorithms:

// TSP Solver
let tspSolution = TspSolver.solveWithDistances distances TspSolver.defaultConfig

// Portfolio Solver  
let portfolio = PortfolioSolver.solveGreedyByRatio assets constraints PortfolioSolver.defaultConfig

📊 Problem Analysis

Analyze problem complexity and characteristics:

match ProblemAnalysis.classifyProblem distances with
| Ok info ->
    printfn "Type: %A" info.ProblemType
    printfn "Size: %d" info.Size
    printfn "Complexity: %s" info.Complexity
| Error msg -> printfn "Error: %s" msg

💰 Cost Estimation

Estimate quantum execution costs before running:

let estimate = CostEstimation.estimateQuantumCost problemSize shots tier
printfn "Estimated cost: $%.2f %s" estimate.EstimatedCost estimate.Currency

📚 Documentation

• Getting Started Guide - Installation and first examples
• API Reference - Complete API documentation
• TSP Example - Detailed TSP walkthrough
• FAQ - Common questions and troubleshooting

🏗️ Architecture

Current Status: v0.1.0-alpha

✅ Completed Components

🚧 In Development

🎯 When to Use Quantum

The library automatically recommends quantum vs classical based on:

Use Classical When:

• ✅ Problem size < 50 variables
• ✅ Need immediate results (milliseconds)
• ✅ Developing/testing locally
• ✅ Cost is a concern

Consider Quantum When:

• ⚡ Problem size > 100 variables
• ⚡ Problem has special structure (QUBO-compatible)
• ⚡ Can tolerate longer wait times (seconds)
• ⚡ Budget available (~$10-100 per run)

Use HybridSolver to decide automatically!

🔧 Development

Prerequisites

• .NET 10.0 SDK
• F# 10.0

Build

dotnet build

Test

dotnet test

All 186 tests passing ✅

Run Examples

cd examples
dotnet run

📊 Performance

Classical Solvers (Local Execution):

🤝 Contributing

Contributions welcome! This is an alpha release and we're actively improving.

Areas for Contribution

• Additional problem domains (Scheduling, MaxCut, etc.)
• Quantum backend integration
• Performance optimizations
• Documentation improvements
• Bug fixes

Development Process

• Follow TDD methodology (see docs-for-mulder/AI-DEVELOPMENT-GUIDE.md)
• Write tests first (RED → GREEN → REFACTOR)
• Update documentation
• Submit PR to dev branch

📄 License

Unlicense - Public domain. Use freely for any purpose.

🙏 Acknowledgments

Built with:

• F# 10.0
• .NET 10.0
• Azure Quantum platform

Developed using AI-assisted TDD methodology.

📞 Support

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

Status: Alpha (v0.1.0) - Classical solvers production-ready, quantum integration coming soon.

Last Updated: 2025-11-24