@neural-trader/example-quantum-optimization

Quantum-inspired optimization algorithms with swarm-based circuit exploration for combinatorial and constraint problems. Implements QAOA, VQE, Quantum Annealing, and intelligent circuit design using AgentDB for pattern learning.

Features

- QAOA (Quantum Approximate Optimization Algorithm) - Hybrid quantum-classical algorithm for combinatorial problems
- VQE (Variational Quantum Eigensolver) - Ground state energy computation and optimization
- Quantum Annealing Simulation - Quantum tunneling and thermal annealing for global optimization
- Swarm Circuit Exploration - Multi-agent exploration of quantum circuit designs with AgentDB
- Memory-Based Learning - Pattern recognition and self-learning optimal circuit depths
- OpenRouter Integration - LLM-powered problem decomposition and circuit suggestions
- Quantum vs Classical Comparison - Comprehensive benchmarking tools

Installation

``bash
npm install @neural-trader/example-quantum-optimization
`

Quick Start

$3

`typescript
import { solveMaxCut } from '@neural-trader/example-quantum-optimization';

// Define graph edges [node1, node2, weight]
const edges: [number, number, number][] = [
[0, 1, 1],
[1, 2, 1],
[2, 3, 1],
[3, 0, 1],
[0, 2, 1]
];

const result = await solveMaxCut(edges, {
depth: 3, // QAOA circuit depth
maxIterations: 100,
learningRate: 0.1,
tolerance: 1e-6
});

console.log('Best Cut:', result.bestSolution);
console.log('Cut Value:', -result.bestEnergy);
console.log('Converged:', result.converged);
console.log('Time:', result.executionTime, 'ms');
`

$3

`typescript
import { VQESolver, createIsingHamiltonian } from '@neural-trader/example-quantum-optimization';

// Create Ising Hamiltonian
const hamiltonian = createIsingHamiltonian(
[[0, 1, 0], [1, 0, 1], [0, 1, 0]], // ZZ couplings
[-0.5, -0.5, -0.5] // Z fields
);

const solver = new VQESolver(
{
numQubits: 3,
ansatzType: 'hardware-efficient',
ansatzDepth: 3,
maxIterations: 100,
optimizer: 'adam',
learningRate: 0.1,
tolerance: 1e-6
},
hamiltonian
);

const result = await solver.solve();

console.log('Ground State Energy:', result.groundStateEnergy);
console.log('Optimal Parameters:', result.optimalParameters);
console.log('Energy History:', result.energyHistory);
`

$3

`typescript
import { solveTSPAnnealing } from '@neural-trader/example-quantum-optimization';

const distanceMatrix = [
[0, 10, 15, 20],
[10, 0, 35, 25],
[15, 35, 0, 30],
[20, 25, 30, 0]
];

const result = await solveTSPAnnealing(distanceMatrix, {
initialTemperature: 100,
finalTemperature: 0.1,
numSteps: 2000,
quantumStrength: 15,
method: 'quantum-monte-carlo'
});

console.log('Best Tour:', result.solution);
console.log('Tour Length:', result.energy);
console.log('Success Probability:', result.successProbability);
console.log('Annealing Path:', result.annealingPath.length, 'steps');
`

$3

`typescript
import { exploreCircuits } from '@neural-trader/example-quantum-optimization';

const result = await exploreCircuits({
numQubits: 4,
problemType: 'maxcut',
swarmSize: 20,
maxDepth: 5,
explorationSteps: 100,
learningRate: 0.01,
memorySize: 1000,
useOpenRouter: true,
openrouterApiKey: process.env.OPENROUTER_API_KEY
});

console.log('Best Circuit Depth:', result.bestCircuit.depth);
console.log('Circuit Performance:', result.bestPerformance);
console.log('Learned Patterns:', result.learnedPatterns.length);
console.log('Converged:', result.convergenceData.converged);

// Analyze learned patterns
result.learnedPatterns.forEach(pattern => {
console.log(Pattern: ${pattern.pattern});
console.log(Frequency: ${pattern.frequency});
console.log(Avg Performance: ${pattern.averagePerformance});
});
`

Unified API

$3

High-level API for common quantum optimization tasks:

`typescript
import { QuantumOptimizer } from '@neural-trader/example-quantum-optimization';

// Auto-select best method for MaxCut
const maxcutResult = await QuantumOptimizer.solveMaxCut(edges, 'auto');

// Solve TSP
const tspResult = await QuantumOptimizer.solveTSP(distanceMatrix);

// Portfolio optimization
const portfolioResult = await QuantumOptimizer.optimizePortfolio(
returns,
covarianceMatrix,
budget,
riskAversion
);

// Constraint satisfaction
const cspResult = await QuantumOptimizer.solveConstraintSatisfaction(
numVars,
constraints
);

// Circuit exploration
const circuitResult = await QuantumOptimizer.exploreCircuits({
numQubits: 4,
problemType: 'vqe',
swarmSize: 20,
explorationSteps: 100
});
`

Applications

$3

Find maximum cut in weighted graphs:

`typescript
import { QuantumOptimizer } from '@neural-trader/example-quantum-optimization';

const edges: [number, number, number][] = [
[0, 1, 5], [0, 2, 3], [1, 2, 2],
[1, 3, 4], [2, 3, 6], [2, 4, 2],
[3, 4, 3]
];

const result = await QuantumOptimizer.solveMaxCut(edges, 'qaoa');

// Partition graph into two sets
const set1 = result.solution
.map((bit, idx) => bit === 0 ? idx : -1)
.filter(x => x >= 0);
const set2 = result.solution
.map((bit, idx) => bit === 1 ? idx : -1)
.filter(x => x >= 0);

console.log('Partition 1:', set1);
console.log('Partition 2:', set2);
console.log('Cut Value:', -result.energy);
`

$3

Quantum-inspired portfolio selection:

`typescript
const returns = [0.12, 0.10, 0.08, 0.15, 0.11];
const covarianceMatrix = [
[0.04, 0.02, 0.01, 0.03, 0.01],
[0.02, 0.03, 0.01, 0.02, 0.02],
[0.01, 0.01, 0.02, 0.01, 0.01],
[0.03, 0.02, 0.01, 0.05, 0.02],
[0.01, 0.02, 0.01, 0.02, 0.03]
];

const result = await QuantumOptimizer.optimizePortfolio(
returns,
covarianceMatrix,
3, // Select 3 assets
1.5 // Risk aversion parameter
);

console.log('Asset Allocation:', result.allocation);
console.log('Expected Return:', (result.expectedReturn * 100).toFixed(2) + '%');
console.log('Portfolio Risk:', (result.risk * 100).toFixed(2) + '%');

// Calculate Sharpe ratio
const riskFreeRate = 0.02;
const sharpe = (result.expectedReturn - riskFreeRate) / result.risk;
console.log('Sharpe Ratio:', sharpe.toFixed(2));
`

$3

Find shortest tour visiting all cities:

`typescript
const cities = ['A', 'B', 'C', 'D'];
const distances = [
[0, 10, 15, 20],
[10, 0, 35, 25],
[15, 35, 0, 30],
[20, 25, 30, 0]
];

const result = await QuantumOptimizer.solveTSP(distances);

// Decode tour from solution
const n = cities.length;
const tour: number[] = [];
for (let pos = 0; pos < n; pos++) {
for (let city = 0; city < n; city++) {
if (result.tour[pos * n + city] === 1) {
tour.push(city);
break;
}
}
}

console.log('Tour:', tour.map(i => cities[i]).join(' → '));
console.log('Total Distance:', result.distance);
`

$3

Solve systems of constraints:

`typescript
// Example: Solve x0 + x1 = 1, x1 + x2 = 1, x2 + x3 = 1
const constraints = [
{ vars: [0, 1], coeffs: [1, 1], rhs: 1 },
{ vars: [1, 2], coeffs: [1, 1], rhs: 1 },
{ vars: [2, 3], coeffs: [1, 1], rhs: 1 }
];

const result = await QuantumOptimizer.solveConstraintSatisfaction(4, constraints);

console.log('Solution:', result.solution);
console.log('All Constraints Satisfied:', result.satisfied);

// Verify constraints
constraints.forEach(({ vars, coeffs, rhs }, idx) => {
const sum = vars.reduce((s, v, i) => s + coeffs[i] * result.solution[v], 0);
console.log(Constraint ${idx}: ${sum} = ${rhs} ✓);
});
`

$3

Discover optimal quantum circuit architectures:

`typescript
const exploration = await exploreCircuits({
numQubits: 5,
problemType: 'vqe',
swarmSize: 30,
maxDepth: 6,
explorationSteps: 200,
learningRate: 0.02,
memorySize: 2000
});

console.log('Best Circuit:');
console.log(' Depth:', exploration.bestCircuit.depth);
console.log(' Gates:', exploration.bestCircuit.gates.length);
console.log(' Two-Qubit Gates:', exploration.bestCircuit.metadata.twoQubitGateCount);
console.log(' Expressibility:', exploration.bestCircuit.metadata.expressibility.toFixed(3));
console.log(' Entangling Capability:', exploration.bestCircuit.metadata.entanglingCapability.toFixed(3));

// Analyze convergence
const { performanceHistory, diversityHistory } = exploration.convergenceData;
console.log('Initial Performance:', performanceHistory[0].toFixed(3));
console.log('Final Performance:', performanceHistory[performanceHistory.length - 1].toFixed(3));
console.log('Improvement:',
((performanceHistory[performanceHistory.length - 1] / performanceHistory[0] - 1) * 100).toFixed(1) + '%'
);
`

Quantum vs Classical Comparison

Compare quantum-inspired methods against classical algorithms:

`typescript
import { QuantumClassicalComparison } from '@neural-trader/example-quantum-optimization';

const edges: [number, number, number][] = [
[0, 1, 1], [1, 2, 1], [2, 3, 1], [3, 4, 1],
[4, 0, 1], [0, 2, 1], [1, 3, 1], [2, 4, 1]
];

const comparison = await QuantumClassicalComparison.compareMaxCut(edges);

console.log('Quantum Solution:');
console.log(' Energy:', comparison.quantum.energy);
console.log(' Time:', comparison.quantum.time, 'ms');

console.log('Classical Solution:');
console.log(' Energy:', comparison.classical.energy);
console.log(' Time:', comparison.classical.time, 'ms');

console.log('Performance:');
console.log(' Speedup:', comparison.speedup.toFixed(2) + 'x');
console.log(' Quality Ratio:', comparison.qualityRatio.toFixed(2));
console.log(' Winner:', comparison.qualityRatio > 1 ? 'Quantum' : 'Classical');
`

Algorithm Details

$3

Hybrid quantum-classical algorithm that alternates between:
1. Problem Hamiltonian (cost function): Encodes optimization objective
2. Mixer Hamiltonian (quantum superposition): Explores solution space

Key Parameters:
- depth (p): Number of QAOA layers (more = better quality, slower)
- maxIterations: Classical optimization iterations
- learningRate: Parameter update step size
- tolerance: Convergence threshold

Best For:
- Small to medium graphs (< 20 nodes)
- High-quality solutions needed
- When quantum advantage is expected

$3

Finds ground state energies using parameterized quantum circuits:
1. Ansatz: Parameterized circuit (hardware-efficient or UCCSD)
2. Measurement: Compute expectation value of Hamiltonian
3. Classical Optimization: Update parameters to minimize energy

Ansatz Types:
- hardware-efficient: Alternating rotations and entangling gates
- uccsd: Unitary Coupled Cluster (for molecular simulation)

Best For:
- Finding ground states
- Molecular simulation
- Optimization through Hamiltonian minimization

$3

Simulates quantum annealing process:
1. Initialization: Start in quantum superposition
2. Annealing: Gradually reduce quantum fluctuations
3. Measurement: Read out classical solution

Methods:
- simulated: Classical simulated annealing with quantum tunneling
- quantum-monte-carlo: Path integral quantum Monte Carlo
- path-integral: Direct path integral formulation

Best For:
- Large combinatorial problems
- TSP, scheduling, logistics
- When local minima are problematic

$3

Multi-agent exploration of circuit designs:
1. Swarm Initialization: Random circuit population
2. Evaluation: Test circuit performance
3. Learning: Store high-performing patterns in AgentDB
4. Update: Move toward better circuits using PSO dynamics
5. Pattern Recognition: Extract common successful patterns

Best For:
- Automated circuit design
- Finding optimal ansatz for specific problems
- Learning problem-specific circuit structures

Configuration Options

$3

`typescript
interface QAOAConfig {
numQubits: number; // Problem size
depth: number; // QAOA layers (1-10)
maxIterations: number; // Classical optimization steps (50-200)
learningRate: number; // Parameter updates (0.01-0.5)
tolerance: number; // Convergence threshold (1e-6)
}
`

$3

`typescript
interface VQEConfig {
numQubits: number;
ansatzType: 'hardware-efficient' | 'uccsd' | 'custom';
ansatzDepth: number; // Circuit layers (1-5)
maxIterations: number; // Optimization steps (50-200)
optimizer: 'gradient-descent' | 'adam' | 'cobyla';
learningRate: number; // Adam/GD rate (0.01-0.2)
tolerance: number; // Convergence (1e-6)
}
`

$3

`typescript
interface AnnealingConfig {
numQubits: number;
initialTemperature: number; // Start temp (50-200)
finalTemperature: number; // End temp (0.01-1)
annealingTime: number; // Total time (1000-10000)
numSteps: number; // Discrete steps (500-5000)
quantumStrength: number; // Transverse field (5-20)
method: 'simulated' | 'quantum-monte-carlo' | 'path-integral';
}
`

$3

`typescript
interface CircuitExplorationConfig {
numQubits: number;
problemType: 'maxcut' | 'vqe' | 'qaoa' | 'custom';
swarmSize: number; // Number of agents (10-50)
maxDepth: number; // Max circuit depth (3-10)
explorationSteps: number; // Iterations (50-500)
learningRate: number; // Learning rate (0.001-0.1)
memorySize: number; // AgentDB size (100-10000)
useOpenRouter?: boolean; // Enable LLM assistance
openrouterApiKey?: string; // API key
}
`

Performance Tips

$3

`bash
npm test
`

Run specific test suites:

`bash
npm test -- qaoa
npm test -- vqe
npm test -- annealing
npm test -- swarm
npm test -- comparison
`

Examples

See the examples/ directory for complete examples:

- maxcut.ts - Graph partitioning
- portfolio.ts - Financial optimization
- tsp.ts - Routing problems
- circuits.ts - Automated circuit design
- comparison.ts - Quantum vs classical benchmarks

API Reference

$3

- QAOAOptimizer - Quantum Approximate Optimization Algorithm
- VQESolver - Variational Quantum Eigensolver
- QuantumAnnealer - Quantum annealing simulation
- SwarmCircuitExplorer - Multi-agent circuit exploration
- QuantumOptimizer - Unified high-level API
- QuantumClassicalComparison - Benchmarking tools

$3

- createMaxCutProblem() - Convert edges to QAOA problem
- createIsingHamiltonian() - Create Hamiltonian for VQE
- QUBOFormulator.maxCutToQUBO() - MaxCut → QUBO
- QUBOFormulator.tspToQUBO() - TSP → QUBO
- QUBOFormulator.portfolioToQUBO() - Portfolio → QUBO
- QUBOFormulator.constraintSatisfactionToQUBO() - CSP → QUBO

Requirements

- Node.js >= 18.0.0
- Dependencies:
- agentdb - Vector database for pattern learning
- mathjs - Mathematical operations
- openai` - Optional LLM integration

License

MIT

Contributing

Contributions welcome! Areas of interest:

- Real quantum hardware backends (IBM, Rigetti, IonQ)
- Additional optimization algorithms (ADMM, gradient-free methods)
- More problem formulations (scheduling, protein folding)
- Performance optimizations (GPU acceleration, parallelization)
- Circuit optimization techniques

References

- QAOA: Farhi et al., "A Quantum Approximate Optimization Algorithm" (2014)
- VQE: Peruzzo et al., "A variational eigenvalue solver on a photonic quantum processor" (2014)
- Quantum Annealing: Kadowaki & Nishimori, "Quantum annealing in the transverse Ising model" (1998)
- Circuit Learning: Sim et al., "Expressibility and entangling capability of parameterized quantum circuits" (2019)

Support

For issues, questions, or contributions:
- GitHub Issues: neural-trader
- Documentation: neural-trader.dev

---

Note: This package implements quantum-inspired algorithms using classical simulation. No real quantum hardware is required or used. For production quantum computing, consider integrating with actual quantum backends (IBM Qiskit, AWS Braket, etc.).