/**
 * Exact density matrix simulation for mixed-state and noise research.
 *
 * Representation: sparse Map<bigint, Complex> where key = (row << n) | col,
 * with n = qubits.  Only entries with |ρ[r][c]|² > 1e-14 are stored.
 *
 * Complexity: O(4ⁿ) in the worst case — practical up to ~12 qubits.
 */
import { Complex } from './complex.js';
import { Gate2x2, Gate4x4 } from './statevector.js';
/** Sparse density matrix.  Key = (row << n) | col. */
type DM = Map<bigint, Complex>;
/**
 * Exact mixed-state density matrix returned by `circuit.dm()`.
 *
 * For n qubits the state space has 4ⁿ entries in the worst case.
 * In practice, near-pure states and modest noise keep the DM very sparse.
 *
 * All bitstring keys follow the standard convention: qubit 0 is the leftmost character.
 */
export declare class DensityMatrix {
    #private;
    readonly qubits: number;
    /** @internal */
    constructor(qubits: number, dm: DM);
    /** ρ[row][col]. */
    get(row: bigint, col: bigint): Complex;
    /**
     * Diagonal probabilities: P(bitstring) = ρ[bs][bs].
     *
     * Keys are standard bitstrings (q0 leftmost).  Only non-negligible values
     * (> 1e-14) are included.
     */
    probabilities(): Readonly<Record<string, number>>;
    /**
     * Purity Tr(ρ²) = Σ_{r,c} |ρ[r][c]|².
     *
     * Equals 1 for a pure state; equals 1/2ⁿ for the maximally mixed state.
     * Values below 1 indicate entanglement-induced or noise-induced mixing.
     */
    purity(): number;
    /**
     * Von Neumann entropy S = −Tr(ρ log₂ ρ) in bits.
     *
     * Computed by diagonalising the full 2ⁿ × 2ⁿ density matrix via Jacobi
     * iteration.  Practical for n ≤ 8 (matrix size ≤ 256 × 256).
     *
     * @throws RangeError for n > 12 (4096 × 4096 matrix — too expensive).
     */
    entropy(): number;
    /**
     * Bloch sphere coordinates (θ, φ) for qubit q from the reduced density matrix.
     *
     * Computes ρ_q = Tr_{others}(ρ) then extracts:
     *   rx = 2·Re(ρ_q[0][1]),  ry = −2·Im(ρ_q[0][1]),  rz = ρ_q[0][0] − ρ_q[1][1]
     *
     * - θ = arccos(rz)  ∈ [0, π]
     * - φ = atan2(ry, rx)  ∈ (−π, π]
     */
    blochAngles(q: number): {
        theta: number;
        phi: number;
    };
}
/** Noise parameters for density matrix simulation (same shape as NoiseParams). */
export interface DmNoiseParams {
    p1?: number;
    p2?: number;
}
/** Published IonQ device profiles — mirrored from circuit.ts. */
export declare const DM_DEVICE_NOISE: Readonly<Record<string, DmNoiseParams>>;
/** Op types that runDM can simulate (classical ops excluded — use pure circuits). */
export type DmOp = {
    kind: 'single';
    q: number;
    gate: Gate2x2;
} | {
    kind: 'cnot';
    control: number;
    target: number;
} | {
    kind: 'swap';
    a: number;
    b: number;
} | {
    kind: 'two';
    a: number;
    b: number;
    gate: Gate4x4;
} | {
    kind: 'controlled';
    control: number;
    target: number;
    gate: Gate2x2;
} | {
    kind: 'toffoli';
    c1: number;
    c2: number;
    target: number;
} | {
    kind: 'cswap';
    control: number;
    a: number;
    b: number;
} | {
    kind: 'csrswap';
    control: number;
    a: number;
    b: number;
} | {
    kind: 'unitary';
    qubits: readonly number[];
    matrix: readonly (readonly Complex[])[];
};
/**
 * Simulate `ops` on the |0…0⟩⟨0…0| initial state and return the exact
 * density matrix, optionally with per-gate depolarizing noise.
 */
export declare function runDM(ops: readonly DmOp[], qubits: number, noise?: DmNoiseParams): DensityMatrix;
export {};
//# sourceMappingURL=density.d.ts.map