Frequently Asked Questions (FAQ)

Common questions about FSharp.Azure.Quantum.

🔥 Quick Troubleshooting Guide

Start here if something isn’t working!

Symptom Quick Fix
“Distance matrix must be square” Ensure rows = columns = number of cities
“Budget insufficient” Budget must be ≥ cheapest asset price
Compiler error on solution.Result Use match on Result type (see Error Handling)
Very slow first run Normal - .NET JIT compilation. Second run will be fast.
Suboptimal solutions Increase MaxIterations to 50000+ or run multiple times
Type inference error Add explicit type annotations: list<string * float * float>
“MinHolding cannot exceed MaxHolding” Check constraint values: MinHolding ≤ MaxHolding ≤ Budget

Still stuck? See detailed Errors and Troubleshooting below.

General Questions

What is FSharp.Azure.Quantum?

FSharp.Azure.Quantum is a quantum-first F# library for solving combinatorial optimization problems using quantum algorithms (QAOA, VQE, QFT). It provides:

Do I need an Azure account to use this library?

No! The LocalBackend (default) provides quantum simulation entirely offline without Azure credentials. You only need Azure access if you want to use cloud quantum backends (IonQ, Rigetti) for larger problems or real quantum hardware.

###Is this production-ready?

Currently 1.1.0 - suitable for:

LocalBackend provides fast, free quantum simulation for problems up to 20 qubits. For larger problems, cloud backends (IonQ, Rigetti) are available via Azure Quantum.

Technical Questions

When should I use quantum vs HybridSolver?

Quick Comparison Table

Aspect Direct Quantum API HybridSolver (with classical fallback)
Approach QAOA/VQE quantum algorithms Auto-routes: Quantum (≥20 vars) or Classical (< 20 vars)
Speed LocalBackend: 1-10s, Cloud: 30-120s Very small: <100ms, Others: same as quantum
Cost LocalBackend: Free, Cloud: $10-100/run Optimizes cost for very small problems
Problem Size 5-200 variables (LocalBackend: ≤20 qubits) 5-500 variables
Best For Consistent quantum API, learning, fixed-size problems Variable-size production workloads
Availability âś… Now (LocalBackend + Cloud) âś… Now
Backend LocalBackend (default) or Cloud (IonQ/Rigetti) Same, but optimizes very small problems
Reproducible ⚠️ Probabilistic (quantum nature) Classical fallback: ✅ Deterministic

Decision Criteria

Use Direct Quantum API when:

Use HybridSolver when:

Example:

// Direct Quantum API (Recommended for most cases)
match GraphColoring.solve problem 4 None with  // Uses QAOA on LocalBackend
| Ok solution -> printfn "Colors used: %d" solution.ColorsUsed
| Error err -> eprintfn "Error: %s" err.Message

// HybridSolver (Optimizes very small problems automatically)
match HybridSolver.solveGraphColoring problem 4 None None None with
| Ok solution -> 
    printfn "Method: %A" solution.Method  // Classical or Quantum
    printfn "Reasoning: %s" solution.Reasoning
| Error err -> eprintfn "Error: %s" err.Message

Crossover Point: HybridSolver routes to classical for < 20 variables, quantum for ≥ 20 variables. For most use cases, direct quantum API is simpler and sufficient.

How accurate are the solutions?

Quantum algorithms (QAOA/VQE) provide:

Solution quality improves with:

Classical fallback (via HybridSolver) provides:

What problem sizes can I solve?

TSP (Traveling Salesman):

Portfolio Optimization:

Performance scales approximately O(n²) for most problems.

Can I use my own distance calculations?

Yes! Just build a distance matrix:

// Custom distance function
let myDistance (city1, city2) = 
    // Your calculation here
    calculateCustomDistance city1 city2

// Build matrix
let distances = 
    Array2D.init n n (fun i j ->
        if i = j then 0.0
        else myDistance (cities.[i], cities.[j]))

Errors and Troubleshooting

“Distance matrix must be square”

Problem: Your distance matrix has different number of rows and columns.

Solution:

// ❌ Wrong: 3x2 matrix
let wrong = array2D [[0.0; 1.0]; [2.0; 0.0]; [3.0; 4.0]]

// âś… Correct: 3x3 matrix
let correct = array2D [
    [0.0; 1.0; 2.0]
    [1.0; 0.0; 3.0]
    [2.0; 3.0; 0.0]
]

“Distance matrix contains negative values”

Problem: Negative distances aren’t supported.

Solution: Ensure all distances are >= 0.0:

// Normalize or shift if needed
let normalized = 
    distances 
    |> Array2D.map (fun d -> max 0.0 d)

Solutions seem suboptimal

Try these improvements:

  1. Increase iterations: 
    let config = { TspSolver.defaultConfig with MaxIterations = 50000 }
  2. Adjust max iterations: 
    match HybridSolver.solveTsp distances None None (Some HybridSolver.SolverMethod.Classical) with
| Ok solution -> printfn "Tour length: %.2f" solution.Result.TourLength
| Error err -> printfn "Error: %s" err.Message
  3. Run multiple times with quantum optimization: 
    [1..10]
|> List.map (fun _ -> 
 match HybridSolver.solveTsp distances None None None with
 | Ok solution -> Some solution
 | Error _ -> None)
|> List.choose id
|> List.minBy (fun sol -> sol.Result.TourLength)

How do I debug slow performance?

Profile your problem:

open System.Diagnostics

let sw = Stopwatch.StartNew()
match HybridSolver.solveTsp distances None None None with
| Ok solution -> 
    sw.Stop()
    printfn "Size: %d cities" (distances.GetLength(0))
    printfn "Time: %d ms" sw.ElapsedMilliseconds
    printfn "Method: %A" solution.Method
| Error err -> printfn "Error: %s" err.Message

printfn “Time per iteration: %.2f ms” (float sw.ElapsedMilliseconds / float solution.Iterations)


## Feature Questions

### Is quantum backend available yet?

**Status:** âś… Quantum algorithms are fully implemented and available via LocalBackend (default) and Azure Quantum cloud backends (IonQ, Rigetti).

**Direct Quantum API:**
- QAOA for optimization problems (GraphColoring, MaxCut, Knapsack, TSP, Portfolio, NetworkFlow)
- VQE for quantum chemistry
- QFT-based algorithms (Shor's, Phase Estimation, Quantum Arithmetic)
- Runs on LocalBackend (free, up to 20 qubits) or cloud backends

**HybridSolver:** Adds classical fallback optimization for very small problems (< 20 variables) where quantum circuit overhead isn't beneficial yet.

### What quantum algorithms are used?

**Optimization Problems (QAOA-based):**
- GraphColoring: QAOA with K-coloring QUBO encoding
- MaxCut: QAOA with graph cut maximization
- Knapsack: QAOA with 0/1 knapsack constraints
- TSP: QAOA with tour feasibility constraints
- Portfolio: QAOA with budget and risk constraints  
- NetworkFlow: QAOA with flow conservation

**Quantum Chemistry (VQE):**
- Variational Quantum Eigensolver for molecular ground state energies
- Supports custom Hamiltonians
- Hardware-efficient ansatz circuits

**QFT-Based Applications:**
- Shor's Algorithm: Period finding for integer factorization
- Phase Estimation: Eigenvalue extraction for quantum chemistry
- Quantum Arithmetic: Modular exponentiation using QFT

**Classical Fallback (HybridSolver only):**
- TSP: Nearest Neighbor + 2-opt local search
- Portfolio: Greedy selection by return/risk ratio

### Can I add my own optimization problems?

Yes! The library is designed to be extensible:

1. Define your problem types
2. Implement solver logic
3. Integrate with HybridSolver
4. Use QuantumAdvisor for recommendations

See [API Reference](/FSharp.Azure.Quantum/api-reference.html) for extensibility patterns.

### Does it support GPU acceleration?

**Currently:** No GPU support.

**Future:** May add GPU-accelerated solvers for larger problems.

## Integration Questions

### How do I integrate with my existing F# code?

```fsharp
// Add package reference
// dotnet add package FSharp.Azure.Quantum

// Open namespace
open FSharp.Azure.Quantum.Classical

// Use in your code
let optimizeTour cities distances =
    match HybridSolver.solveTsp distances None None None with
    | Ok solution -> Some solution.Result
    | Error _ -> None

Can I use this from C#?

Yes! F# libraries are fully interoperable:

using FSharp.Azure.Quantum.Classical;

var distances = new double[,] {
    {0.0, 2.0, 9.0},
    {1.0, 0.0, 6.0},
    {15.0, 7.0, 0.0}
};

var result = HybridSolver.solveTsp(
    distances, 
    FSharpOption<double>.None, 
    FSharpOption<double>.None, 
    FSharpOption<HybridSolver.SolverMethod>.None
);

if (FSharpResult<Solution, string>.get_IsOk(result)) {
    var solution = result.ResultValue;
    Console.WriteLine($"Tour length: {solution.Result.TourLength}");
}

Does it work with .NET 8/9/10?

Targets: .NET 10.0

Compatible with: .NET 10.0 or later

Not compatible: .NET Framework, .NET Core 3.1, .NET 5/6/7

Cost and Licensing

How much does it cost?

Library: Free and open source (Unlicense license)

LocalBackend (Quantum Simulation): Free - runs entirely local, up to 20 qubits

Cloud Quantum Backends: Azure Quantum pricing applies

What license is it under?

Unlicense - public domain equivalent:

Support Questions

Where can I get help?

How do I report a bug?

  1. Check existing issues
  2. Create minimal reproduction
  3. Include:
    • F#/.NET version
    • Library version
    • Code sample
    • Expected vs actual behavior

How can I contribute?

Contributions welcome!

See CONTRIBUTING.md (if available) or open an issue to discuss.

Performance Questions

Why is my first call slow?

.NET JIT compilation - first call includes:

Solution: Warm up with a small problem first:

// Warm up JIT
let _ = TspSolver.solveWithDistances (array2D [[0.0]]) TspSolver.defaultConfig

// Now solve real problem
let solution = TspSolver.solveWithDistances largeDistances config

How do I parallelize multiple solves?

Use F# async or parallel collections:

// Parallel solves with different seeds
let solutions = 
    [1..10]
    |> List.map (fun seed -> 
        async {
            let config = { TspSolver.defaultConfig with RandomSeed = Some seed }
            return TspSolver.solveWithDistances distances config
        })
    |> Async.Parallel
    |> Async.RunSynchronously
    |> Array.minBy (fun sol -> sol.TourLength)

Still have questions?