Bernstein-Vazirani Algorithm

The Bernstein-Vazirani algorithm is a quantum algorithm that efficiently
determines a hidden bit string s using only one query to a quantum oracle.
It is a foundational example of quantum speedup over classical algorithms,
demonstrating how quantum circuits can solve specific problems more
efficiently than their classical counterparts.

This implementation builds the quantum circuit for the Bernstein-Vazirani
algorithm and executes it on a specified quantum backend.

The algorithm uses a quantum oracle Uf that computes f(x) = s·x (mod 2),
where s is the hidden string and x is the input bit string.

The algorithm requires only one query to the oracle to determine the hidden
string s, while classical algorithms would require n queries for an n-bit
string.

Deutsch Algorithm

The Deutsch algorithm is a quantum algorithm that determines whether a given
function f: {0,1} → {0,1} is constant (f(0) = f(1)) or balanced (f(0) ≠ f(1))
using only one quantum query, compared to 2 classical queries needed.

This implementation builds the quantum circuit for the Deutsch algorithm
and executes it on a specified quantum backend.

Grover's Search Algorithm

Grover's algorithm provides a quadratic speedup for searching unsorted databases.
For N items, classical search requires O(N) queries, while Grover's requires O(√N).
The number of Grover iterations is approximately π√N/4, where N is the size
of the search space.

This implementation builds the quantum circuit for Grover's algorithm and executes it
on a specified quantum backend.

The algorithm consists of:
1. Initializing a uniform superposition state |+⟩^⊗n
2. Repeating Grover iterations:
   a. Apply the oracle Uf to mark target states
   b. Apply the diffusion operator (inversion about average)
3. Measuring the final state to find the target item with high probability

The oracle function should take a computational basis state index and return
true for target states.

The diffusion operator applies inversion about the average amplitude.

HHL (Harrow-Hassidim-Lloyd) Algorithm

The HHL algorithm is a quantum algorithm for solving linear systems of equations 
of the form Ax = b, where A is a Hermitian matrix. It provides exponential speedup 
over classical algorithms for certain classes of linear systems.

The algorithm works by:
1. Encoding the vector b as a quantum state |b⟩
2. Using quantum phase estimation to find eigenvalues of A
3. Performing conditional rotation to compute A^(-1)
4. Amplitude amplification to extract the solution

This implementation is designed for production use with:
- General n×n Hermitian matrices
- Integration with existing quantum phase estimation
- Proper error handling and validation
- Configurable precision and success probability

Key functions:
- matrix-encoding-unitary: Encode Hermitian matrix as unitary evolution
- vector-preparation-circuit: Prepare |b⟩ state from classical vector
- hhl-circuit: Build complete HHL quantum circuit
- hhl-algorithm: Execute HHL algorithm with backend

∂⟨H⟩/∂θ = (1/2)[⟨H⟩(θ + π/2) - ⟨H⟩(θ - π/2)]

;; Basic Adam optimization
(adam-optimization objective-fn initial-params
  {:learning-rate 0.01
   :max-iterations 500
   :tolerance 1e-6
   :gradient-method :parameter-shift})

;; Quantum Natural Gradient with Fisher Information
(quantum-natural-gradient-optimization objective-fn initial-params
  {:ansatz-fn ansatz-constructor
   :backend quantum-backend
   :learning-rate 0.1
   :fisher-regularization 1e-8})

;; Robust derivative-free optimization
(fastmath-derivative-free-optimization :cmaes objective-fn initial-params
  {:max-iterations 2000
   :cmaes-sigma 0.3
   :parameter-bounds [[-π π] [-π π]]})

Quantum optimization algorithms and gradient computation for variational quantum algorithms.

This namespace provides a comprehensive suite of optimization methods specifically designed
for quantum variational algorithms like VQE, QAOA, and quantum machine learning. It combines
quantum-aware gradient computation with classical optimization techniques to achieve efficient
parameter optimization on quantum circuits.

Core features
 
Quantum Gradient Computation:
- **Parameter Shift Rule**: Exact gradients for parameterized quantum circuits
- **Finite Differences**: General gradient computation for classical functions
- **Adaptive Parameter Shifts**: Optimized shifts for different parameter types
- **Parallel Gradient Evaluation**: Efficient computation using multiple threads

Classical Optimization Methods:
- **Gradient Descent**: Basic optimization with momentum and adaptive learning rates
- **Adam Optimizer**: Adaptive moment estimation with bias correction
- **Quantum Natural Gradient**: Fisher Information Matrix-based natural gradients
- **Fastmath Integration**: Derivative-free and gradient-based external optimizers

Quantum Fisher Information:
- **QFIM Computation**: Quantum Fisher Information Matrix calculation
- **Natural Gradient Updates**: Optimal parameter space metrics
- **Matrix Operations**: Linear algebra utilities for quantum optimization
- **Regularization**: Numerical stability for ill-conditioned systems

Optimization Method Selection Guide

For Quantum Variational Algorithms (VQE, QAOA):
- **:adam** - Fast convergence, adaptive learning rates (recommended default)
- **:gradient-descent** - Simple, reliable, theoretical guarantees
- **:quantum-natural-gradient** - Optimal convergence in quantum parameter space

For Noisy or Difficult Landscapes:
- **:cmaes** - Robust global optimization, handles noise well
- **:nelder-mead** - Derivative-free simplex method
- **:powell** - Coordinate descent without gradients

For High-Precision Requirements:
- **:quantum-natural-gradient** - Uses quantum Fisher information
- **:adam** - With small learning rates and tight tolerances

Parameter Shift Rule

The parameter shift rule is fundamental to quantum optimization:
```
∂⟨H⟩/∂θ = (1/2)[⟨H⟩(θ + π/2) - ⟨H⟩(θ - π/2)]
```

This provides exact gradients for quantum circuits with rotation gates,
requiring only 2 circuit evaluations per parameter.

Usage Examples

```clojure
;; Basic Adam optimization
(adam-optimization objective-fn initial-params
  {:learning-rate 0.01
   :max-iterations 500
   :tolerance 1e-6
   :gradient-method :parameter-shift})

;; Quantum Natural Gradient with Fisher Information
(quantum-natural-gradient-optimization objective-fn initial-params
  {:ansatz-fn ansatz-constructor
   :backend quantum-backend
   :learning-rate 0.1
   :fisher-regularization 1e-8})

;; Robust derivative-free optimization
(fastmath-derivative-free-optimization :cmaes objective-fn initial-params
  {:max-iterations 2000
   :cmaes-sigma 0.3
   :parameter-bounds [[-π π] [-π π]]})
```

Integration with VQE

This namespace is designed to integrate seamlessly with VQE and other
variational quantum algorithms. The optimization functions expect:
- **Objective Function**: Takes parameter vector, returns scalar energy
- **Initial Parameters**: Starting point for optimization
- **Options Map**: Configuration for optimization behavior

Performance Considerations

- **Parameter Shift**: 2N circuit evaluations per gradient (N = parameters)
- **Finite Differences**: 2N circuit evaluations per gradient  
- **Quantum Natural Gradient**: N² + 2N circuit evaluations per iteration
- **Derivative-Free**: Varies by method, typically 10-100x more evaluations

Design Principles

- **Quantum-Aware**: Exploits quantum circuit structure for efficiency
- **Flexible**: Supports multiple optimization strategies
- **Robust**: Handles numerical instabilities and edge cases
- **Extensible**: Easy to add new optimization methods
- **Production-Ready**: Suitable for real quantum hardware

See also: `org.soulspace.qclojure.application.algorithm.vqe` for usage in VQE.

Production-ready quantum arithmetic circuits with minimal resource usage.

This namespace provides a complete suite of quantum arithmetic operations
needed for algorithms like Shor's factoring, quantum period finding,
and other cryptographic quantum algorithms.

This implementation focuses on:
- Minimal qubit usage (qubits are sparse resources)
- Correct quantum arithmetic from the start
- Proper testing at each level
- Production-ready code that will work on real quantum hardware

All circuits are designed to be:
- Reversible (essential for quantum computation)
- Resource-efficient (minimizing ancilla qubits)
- Fault-tolerant ready (structured for error correction)
- Modular and composable

Quantum period finding algorithm for Shor's algorithm.

This algorithm is a specialized application of quantum phase estimation (QPE)
to find the period of the modular exponentiation function f(x) = a^x mod N.

Instead of reimplementing QPE, this module leverages the existing quantum-phase-estimation
algorithm and adapts it for period finding by:
1. Setting up the appropriate unitary operator (modular exponentiation)
2. Using QPE to estimate the phase
3. Converting phase estimates to period estimates using continued fractions

This follows the DRY principle and maintains a clean separation of concerns.

Version 2.0: Now uses the comprehensive quantum arithmetic module for
production-ready modular exponentiation circuits.

Quantum Phase Estimation (QPE) algorithm implementation.

The Quantum Phase Estimation algorithm is a fundamental quantum algorithm that estimates
the eigenvalue of a unitary operator. Given a unitary operator U and one of its 
eigenstates |ψ⟩ such that U|ψ⟩ = e^(iφ)|ψ⟩, QPE estimates the phase φ.

Algorithm Overview:
1. Initialize precision qubits in superposition (|+⟩ states)
2. Prepare eigenstate qubit in a known eigenstate of U
3. Apply controlled-U^(2^k) operations for k = 0 to n-1
4. Apply inverse Quantum Fourier Transform to precision qubits
5. Measure precision qubits to extract phase estimate

The precision of the phase estimate depends on the number of precision qubits used.
With n precision qubits, the phase can be estimated to within 2π/2^n.

Key Functions:
- quantum-phase-estimation-circuit: Build QPE circuit
- quantum-phase-estimation: Execute complete QPE algorithm
- parse-measurement-to-phase: Convert measurement results to phase estimates
- analyze-qpe-results: Analyze QPE measurement statistics

Example Usage:
(def simulator (create-simulator))
(def result (quantum-phase-estimation simulator (/ Math/PI 4) 3 :plus))
(:estimated-phase (:result result)) ; => ~0.7854 (π/4)

Simon's Algorithm

Simon's algorithm solves the hidden subgroup problem for the group (Z₂)ⁿ.
Given a function f: {0,1}ⁿ → {0,1}ⁿ that is either one-to-one or two-to-one,
and if two-to-one then f(x) = f(x ⊕ s) for some hidden string s ≠ 0ⁿ,
the algorithm finds s with exponential speedup over classical methods.

The algorithm requires only O(n) quantum operations to find the hidden period,
while classical algorithms would require O(2^(n/2)) queries to find s.

This implementation builds the quantum circuit for Simon's algorithm
and executes it on a specified quantum backend.

The algorithm uses a quantum oracle Uf that computes f(x) = f(x ⊕ s),
where s is the hidden period and x is the input bit string.

Variational Quantum Eigensolver (VQE) Algorithm Implementation

VQE is a quantum-classical hybrid algorithm for finding the ground state energy
of quantum systems. It uses a parameterized quantum circuit (ansatz) to prepare
trial states and classical optimization to minimize the energy expectation value.

Key Features:
- Multiple ansatz types (hardware-efficient, UCCSD-inspired, symmetry-preserving)
- Pauli string Hamiltonian representation with measurement grouping
- Integration with fastmath optimization for classical optimization
- Comprehensive analysis and convergence monitoring
- Support for both gate-based and measurement-based implementations

Algorithm Flow:
1. Initialize parameterized quantum circuit (ansatz)
2. Prepare trial state |ψ(θ)⟩ with parameters θ
3. Measure expectation value ⟨ψ(θ)|H|ψ(θ)⟩
4. Use classical optimizer to update parameters
5. Repeat until convergence

This implementation targets production use with real quantum hardware.

Implementation of fundamental quantum algorithms using the qclojure domain