/**
 * Standard quantum algorithm library.
 *
 * All functions return immutable Circuit instances (or numbers for VQE).
 * Qubit 0 is the least-significant bit throughout.
 */
import { Circuit } from './circuit.js';
/**
 * n-qubit Quantum Fourier Transform.
 * Output convention: qubit 0 = LSB (IonQ / ket standard).
 */
export declare function qft(n: number): Circuit;
/**
 * n-qubit inverse QFT (QFT†).
 */
export declare function iqft(n: number): Circuit;
/**
 * Number of ancilla qubits required by `grover` for an n-qubit search space.
 * The returned circuit has `n + groverAncilla(n)` total qubits;
 * qubits 0..n-1 hold the search register.
 */
export declare function groverAncilla(n: number): number;
/**
 * Grover's search circuit.
 *
 * @param n         Number of search qubits (search space = 2^n).
 * @param oracle    Callback that marks target states with a phase flip on qubits 0..n-1.
 * @param iterations Grover iterations (default: optimal ≈ (π/4)√(2^n)).
 *
 * The circuit has `n + groverAncilla(n)` total qubits.
 * Ancilla qubits (n..) are initialised to |0⟩ and returned to |0⟩ after each diffusion.
 */
export declare function grover(n: number, oracle: (c: Circuit) => Circuit, iterations?: number): Circuit;
/**
 * Quantum Phase Estimation circuit.
 *
 * Estimates the phase φ of an eigenstate |u⟩ such that U|u⟩ = e^{2πiφ}|u⟩.
 *
 * @param precision    Number of counting qubits (phase resolution = 1/2^precision).
 * @param unitary      Callback applied for each counting qubit k: applies controlled-U^{2^k}
 *                     with `control` as the control qubit and `targets` as the target register.
 * @param targetQubits Number of target qubits (default 1).
 *
 * Circuit layout: qubits 0..precision-1 = counting register, qubits precision.. = target register.
 * Initialise the target register to an eigenstate |u⟩ before running.
 */
export declare function phaseEstimation(precision: number, unitary: (c: Circuit, control: number, power: number, targets: number[]) => Circuit, targetQubits?: number): Circuit;
/**
 * Trotterized Hamiltonian simulation: e^{−iHt} ≈ (∏_j e^{−iH_j·t/r})^r.
 *
 * Implements the Lie–Trotter product formula (order=1) and the
 * symmetric Trotter–Suzuki decomposition (order=2) for a Hamiltonian
 * expressed as a sum of Pauli strings.
 *
 * @param n           Number of qubits.
 * @param hamiltonian Pauli-string Hamiltonian — same convention as {@link PauliTerm}:
 *                    `ops[0]` acts on qubit n−1 (MSB), `ops[n−1]` on qubit 0 (LSB).
 * @param t           Total evolution time.
 * @param steps       Number of Trotter steps r (default 1). Error scales as O(t²/r).
 * @param order       1 = first-order, 2 = second-order Suzuki (error O(t³/r²), default 1).
 * @returns           Circuit approximating e^{−iHt}|ψ⟩.
 */
export declare function trotter(n: number, hamiltonian: PauliTerm[], t: number, steps?: number, order?: 1 | 2): Circuit;
/**
 * Max-Cut cost Hamiltonian as a Pauli-string sum.
 *
 * H_C = Σ_{(u,v)∈E} (I − Z_u·Z_v) / 2
 *
 * `vqe(qaoa(n, edges, gamma, beta), maxCutHamiltonian(n, edges))`
 * returns the expected number of cut edges (exact, no sampling).
 */
export declare function maxCutHamiltonian(n: number, edges: readonly [number, number][]): PauliTerm[];
/**
 * QAOA circuit for Max-Cut (Farhi et al. 2014).
 *
 * Circuit: H^⊗n · [U_C(γ_l) · U_B(β_l)]_{l=0..p−1}
 *
 *   U_C(γ) = ∏_{(u,v)∈E} exp(iγ Z_u Z_v / 2)   cost unitary
 *   U_B(β) = ∏_q exp(−iβ X_q)                   mixer unitary
 *
 * Optimise γ and β with `vqe` + a classical optimiser, or sweep analytically
 * for small p. Larger p → better approximation ratio; p=1 already beats
 * the Goemans–Williamson 0.878 SDP bound for some graph families.
 *
 * @param n      Number of nodes (qubits).
 * @param edges  Graph edges — [u, v] pairs, 0-indexed.
 * @param gamma  Cost angles, one per layer.
 * @param beta   Mixer angles, one per layer (must equal gamma.length).
 */
export declare function qaoa(n: number, edges: readonly [number, number][], gamma: readonly number[], beta: readonly number[]): Circuit;
/**
 * A term in a Pauli-string Hamiltonian: coeff · (P_{n-1} ⊗ … ⊗ P_0).
 *
 * `ops` is a string of length n over {I, X, Y, Z}.
 * ops[0] acts on qubit n-1 (MSB); ops[n-1] acts on qubit 0 (LSB).
 */
export interface PauliTerm {
    coeff: number;
    ops: string;
}
/**
 * VQE energy estimate: ⟨ansatz|H|ansatz⟩ for a Pauli-string Hamiltonian.
 *
 * Uses exact statevector probabilities (no sampling noise).
 * Basis rotations: X → H, Y → Rx(π/2), Z → identity.
 *
 * @param ansatz      Circuit that prepares the trial state |ψ⟩.
 * @param hamiltonian List of Pauli terms.
 * @returns           ⟨ψ|H|ψ⟩
 */
export declare function vqe(ansatz: Circuit, hamiltonian: PauliTerm[]): number;
/** An ansatz function paired with its known parameter count. */
export interface AnsatzFn {
    (params: readonly number[]): Circuit;
    /** Total number of trainable parameters. */
    paramCount: number;
}
/**
 * Hardware-efficient ansatz with real amplitudes.
 *
 * Alternating layers of Ry(θ) rotations and linear CNOT entanglement,
 * with a final Ry layer.  All state amplitudes remain real throughout.
 * Total parameters: `n × (reps + 1)`.
 *
 * @example
 * const ansatz = realAmplitudes(2, 2)
 * const { energy } = minimize(ansatz, hamiltonian, Array(ansatz.paramCount).fill(0))
 */
export declare function realAmplitudes(n: number, reps?: number): AnsatzFn;
/**
 * Hardware-efficient ansatz with full SU(2) single-qubit rotations.
 *
 * Alternating layers of Ry(θ)·Rz(φ) rotations and linear CNOT entanglement,
 * with a final Ry·Rz layer.  Total parameters: `2n × (reps + 1)`.
 *
 * Strictly more expressive than `realAmplitudes` — can reach any product state
 * and, with entanglement, arbitrary entangled states.
 */
export declare function efficientSU2(n: number, reps?: number): AnsatzFn;
/**
 * Pauli-string operator with full complex-coefficient arithmetic.
 *
 * Use `PauliOp.from()` to build from a real Hamiltonian and `.toTerms()` to
 * convert back for `vqe()`, `gradient()`, and `minimize()`.
 *
 * @example
 * const H = PauliOp.from([{ coeff: 1, ops: 'ZI' }, { coeff: 1, ops: 'IZ' }])
 * const V = PauliOp.from([{ coeff: 0.5, ops: 'XX' }])
 * const energy = vqe(circuit, H.add(V).toTerms())
 */
export declare class PauliOp {
    #private;
    private constructor();
    /** Construct from a real-coefficient Pauli Hamiltonian. */
    static from(terms: PauliTerm[]): PauliOp;
    /** A + B */
    add(other: PauliOp): PauliOp;
    /** c · A */
    scale(factor: number): PauliOp;
    /** A · B  (Pauli string product with phase tracking) */
    mul(other: PauliOp): PauliOp;
    /** [A, B] = AB − BA */
    commutator(other: PauliOp): PauliOp;
    /**
     * Convert to `PauliTerm[]` for use with `vqe()`, `gradient()`, and `minimize()`.
     * Throws if any imaginary coefficients exceed `tol` (operator is not Hermitian).
     */
    toTerms(tol?: number): PauliTerm[];
}
/**
 * Compute the exact analytic gradient of ⟨ψ(params)|H|ψ(params)⟩ w.r.t. each
 * parameter using the parameter shift rule:
 *
 *   ∂⟨H⟩/∂θᵢ = ½[⟨H⟩(θᵢ + π/2) − ⟨H⟩(θᵢ − π/2)]
 *
 * This is exact (not finite-difference) for any gate of the form e^{−iθP/2}
 * where P is a Pauli operator — i.e. Rx, Ry, Rz, and all standard rotation
 * gates.  It returns 2N evaluations of `vqe()` for N parameters.
 *
 * @param ansatz      Function mapping a parameter vector to a Circuit.
 * @param hamiltonian Pauli-string Hamiltonian (same format as `vqe()`).
 * @param params      Current parameter values θ.
 * @returns           Gradient vector — `result[i]` = ∂⟨H⟩/∂params[i].
 *
 * @example
 * const ansatz = (p: readonly number[]) => new Circuit(1).ry(p[0]!, 0)
 * const H = [{ coeff: 1, ops: 'Z' }]
 * gradient(ansatz, H, [Math.PI / 4])  // ≈ [-0.7071]  (= −sin(π/4))
 */
export declare function gradient(ansatz: (params: readonly number[]) => Circuit, hamiltonian: PauliTerm[], params: readonly number[]): number[];
/** Options for {@link minimize}. */
export interface MinimizeOptions {
    /** Gradient descent learning rate (default `0.1`). */
    lr?: number;
    /** Maximum number of gradient steps (default `200`). */
    steps?: number;
    /** Convergence threshold: stops when gradient L2 norm < tol (default `1e-6`). */
    tol?: number;
}
/** Result returned by {@link minimize} and {@link minimizeMps}. */
export interface MinimizeResult {
    /** Optimal parameters found. */
    params: number[];
    /** ⟨ψ(params)|H|ψ(params)⟩ at those parameters. */
    energy: number;
    /** Number of gradient steps taken. */
    steps: number;
    /** True if the gradient norm dropped below `tol` before exhausting `steps`. */
    converged: boolean;
    /**
     * True if any MPS energy evaluation during the optimization hit the `maxBond` cap and
     * discarded significant singular values. Results are approximate in this case.
     *
     * Always `false` for `minimize()` (exact statevector path).
     * Increase `maxBond` or set `truncErr` to reduce approximation error.
     */
    truncated: boolean;
}
/**
 * Minimize ⟨ψ(params)|H|ψ(params)⟩ with gradient descent + parameter shift.
 *
 * Runs until the gradient L2 norm drops below `tol` or the step budget is
 * exhausted.  Use `gradient()` directly if you need a different optimizer
 * (Adam, L-BFGS, etc.).
 *
 * @example
 * const ansatz = (p: readonly number[]) =>
 *   new Circuit(2).ry(p[0]!, 0).cnot(0, 1).ry(p[1]!, 1)
 * const { energy, params, converged } = minimize(ansatz, H, [0, 0])
 */
export declare function minimize(ansatz: (params: readonly number[]) => Circuit, hamiltonian: PauliTerm[], initialParams: readonly number[], { lr, steps, tol }?: MinimizeOptions): MinimizeResult;
/** Options for {@link minimizeMps}. Extends {@link MinimizeOptions} with MPS backend settings. */
export interface MinimizeMpsOptions extends MinimizeOptions {
    /** Maximum bond dimension χ for the MPS backend (default 64). */
    maxBond?: number;
    /** Relative Schmidt truncation threshold (default 0 = off). */
    truncErr?: number;
}
/**
 * Parameter-shift gradient of ⟨ψ(θ)|H|ψ(θ)⟩ evaluated via MPS.
 *
 * Drop-in replacement for `gradient()` that scales to 50+ qubits.
 * Uses `expectMps()` for each energy evaluation — exact to floating-point
 * precision, no sampling variance.
 *
 * @example
 * const ansatz = realAmplitudes(20, 2)
 * const H = [{ coeff: 1, ops: 'Z'.repeat(20) }]
 * const grad = gradientMps(ansatz, H, params, { maxBond: 32 })
 */
export declare function gradientMps(ansatz: (params: readonly number[]) => Circuit, hamiltonian: PauliTerm[], params: readonly number[], { maxBond, truncErr }?: {
    maxBond?: number;
    truncErr?: number;
}): {
    gradient: number[];
    truncated: boolean;
};
/**
 * Minimize ⟨ψ(θ)|H|ψ(θ)⟩ with gradient descent + parameter shift via MPS.
 *
 * Drop-in replacement for `minimize()` that scales to 50+ qubits.
 * Identical interface — swap `minimize` → `minimizeMps` and add `maxBond`
 * to push VQE beyond the statevector memory wall.
 *
 * @example
 * // 20-qubit Heisenberg ground state — impossible with statevector
 * const ansatz = realAmplitudes(20, 3)
 * const H = heisenbergTerms(20)
 * const { energy, converged } = minimizeMps(ansatz, H, initialParams, { maxBond: 32 })
 */
export declare function minimizeMps(ansatz: (params: readonly number[]) => Circuit, hamiltonian: PauliTerm[], initialParams: readonly number[], { lr, steps, tol, maxBond, truncErr }?: MinimizeMpsOptions): MinimizeResult;
//# sourceMappingURL=algorithms.d.ts.map