ts-quantum/dist/quantum/src/utils/matrixOperations.d.ts

TypeScript library for quantum mechanics calculations and utilities

/**
 * Quantum Matrix Operations
 *
 * This module provides pure functional implementations of matrix operations
 * specifically designed for quantum computations. It focuses on:
 * - Type safety through TypeScript
 * - Proper error handling with detailed messages
 * - Mathematical correctness and numerical stability
 * - Clean functional programming interface
 *
 * Key features:
 * - Complex matrix operations (multiplication, addition, scaling)
 * - Quantum-specific operations (tensor products, adjoints)
 * - Eigendecomposition with support for degenerate cases
 * - Numerical stability handling
 * - Comprehensive error checking
 *
 * @module quantum/matrixOperations
 */
import { Complex, IOperator, IStateVector } from '../core/types';
/**
 * Represents a matrix of complex numbers
 * Each element is a Complex type from mathjs
 */
export type ComplexMatrix = Complex[][];
/**
 * Represents the dimensions of a matrix
 */
export interface IMatrixDimensions {
    /** Number of rows in the matrix */
    rows: number;
    /** Number of columns in the matrix */
    cols: number;
}
/**
 * Result of matrix validation operations
 */
export interface IValidationResult {
    /** Whether the matrix is valid */
    valid: boolean;
    /** Error message if validation failed */
    error?: string;
}
/**
 * Multiplies two complex matrices using standard matrix multiplication
 *
 * For matrices A (m×n) and B (n×p), computes the product C = AB (m×p) where:
 * C[i,j] = Σ(k=0 to n-1) A[i,k] * B[k,j]
 *
 * In quantum mechanics, matrix multiplication represents:
 * - Sequential application of quantum operations
 * - Composition of quantum gates
 * - Transformation of quantum states
 *
 * @param a - First matrix (m×n)
 * @param b - Second matrix (n×p)
 * @returns Result matrix (m×p)
 * @throws Error if matrices have invalid dimensions or elements
 *
 * @example
 * // Multiply Hadamard gate by itself (H² = I)
 * const H = [[1/√2, 1/√2], [1/√2, -1/√2]];
 * const HH = multiplyMatrices(H, H); // Should give identity matrix
 */
export declare function multiplyMatrices(a: ComplexMatrix, b: ComplexMatrix): ComplexMatrix;
/**
 * Computes the adjoint (conjugate transpose) of a matrix
 *
 * The adjoint A† of a matrix A is obtained by taking the complex conjugate
 * of each element and then transposing the matrix. For quantum operators,
 * the adjoint is essential for:
 * - Testing if an operator is Hermitian (A = A†)
 * - Testing if an operator is unitary (A†A = AA† = I)
 * - Computing expectation values ⟨ψ|A|ψ⟩
 *
 * @param matrix - Input matrix
 * @returns Adjoint matrix
 * @throws Error if matrix is invalid
 *
 * @example
 * const matrix = [[{re: 1, im: 1}, {re: 0, im: 0}],
 *                 [{re: 0, im: 0}, {re: 1, im: -1}]];
 * const adj = adjoint(matrix); // Conjugate transpose
 */
export declare function adjoint(matrix: ComplexMatrix): ComplexMatrix;
/**
 * Computes the transpose of a matrix
 *
 * The transpose Aᵀ of a matrix A is obtained by swapping rows and columns.
 *
 * @param matrix - Input matrix
 * @returns Transpose matrix
 * @throws Error if matrix is invalid
 */
export declare function transpose(matrix: ComplexMatrix): ComplexMatrix;
/**
 * Computes tensor product (Kronecker product) of two matrices
 *
 * The tensor product A ⊗ B of matrices A and B is a matrix whose dimension
 * is the product of the dimensions of A and B. It represents the quantum
 * mechanical combination of two quantum systems.
 *
 * @param a - First matrix
 * @param b - Second matrix
 * @returns Tensor product matrix with dimensions (m*p) × (n*q) for m×n and p×q input matrices
 * @throws Error if either matrix is invalid
 *
 * @example
 * const a = [[1, 0], [0, 1]]; // 2×2 identity matrix
 * const b = [[0, 1], [1, 0]]; // Pauli X matrix
 * const result = tensorProduct(a, b); // 4×4 matrix
 */
/**
 * Computes matrix exponential exp(A) for a complex matrix A
 *
 * The matrix exponential is defined as:
 * exp(A) = I + A + A²/2! + A³/3! + ...
 *
 * In quantum mechanics, the matrix exponential is crucial for:
 * - Time evolution: U(t) = exp(-iHt/ħ) where H is the Hamiltonian
 * - Quantum gates: Many gates are exponentials of Pauli matrices
 * - Continuous transformations: exp(θA) gives continuous path of transformations
 *
 * @param matrix - Input matrix (must be square)
 * @returns Matrix exponential result
 * @throws Error if matrix is invalid or non-square
 *
 * @example
 * // Pauli X gate is exp(iπX/2) where X is the Pauli X matrix
 * const X = [[0, 1], [1, 0]];
 * const theta = Math.PI/2;
 * const iX = scaleMatrix(X, {re: 0, im: theta});
 * const expIX = matrixExponential(iX);
 */
export declare function matrixExponential(matrix: ComplexMatrix): ComplexMatrix;
export declare function tensorProduct(a: ComplexMatrix, b: ComplexMatrix): ComplexMatrix;
/**
 * Computes eigendecomposition of a complex matrix
 *
 * This implementation handles both Hermitian and non-Hermitian matrices,
 * supporting complex eigenvalues and eigenvectors. For Hermitian matrices,
 * all eigenvalues are guaranteed to be real.
 *
 * @param matrix Input matrix (can be complex)
 * @param options Configuration options
 * @param options.precision Numerical precision for eigenvalue/eigenvector computation (default: 1e-10)
 * @param options.computeEigenvectors Whether to compute eigenvectors (default: true)
 * @param options.enforceOrthogonality Whether to enforce orthogonality for degenerate eigenvectors (default: true)
 * @returns Object containing eigenvalues and optionally eigenvectors
 * @throws Error if matrix is invalid, non-square, or computation fails
 *
 * @example
 * // Hermitian matrix
 * const matrix = [
 *   [math.complex(1, 0), math.complex(0, 1)],
 *   [math.complex(0, -1), math.complex(1, 0)]
 * ];
 * const { values, vectors } = eigenDecomposition(matrix);
 */
export declare function eigenDecomposition(matrix: ComplexMatrix): {
    values: Complex[];
    vectors?: ComplexMatrix;
};
export declare function eigenDecomposition(matrix: ComplexMatrix, options: {
    precision?: number;
    computeEigenvectors?: true;
    enforceOrthogonality?: boolean;
}): {
    values: Complex[];
    vectors: ComplexMatrix;
};
export declare function eigenDecomposition(matrix: ComplexMatrix, options: {
    precision?: number;
    computeEigenvectors?: false;
    enforceOrthogonality?: boolean;
}): {
    values: Complex[];
    vectors?: undefined;
};
export declare function zeroMatrix(rows: number, cols: number): IOperator;
/**
 * Adds two matrices
 *
 * @param a First matrix
 * @param b Second matrix
 * @returns Sum matrix
 * @throws Error if matrices have incompatible dimensions
 */
export declare function addMatrices(a: ComplexMatrix, b: ComplexMatrix): ComplexMatrix;
/**
 * Scales a matrix by a complex number
 *
 * @param matrix Input matrix
 * @param scalar Complex scaling factor
 * @returns Scaled matrix
 * @throws Error if matrix is invalid
 */
/**
 * Normalizes a matrix by dividing by its trace
 * This is particularly useful for density matrices which must have trace 1
 *
 * @param matrix Input matrix
 * @returns Normalized matrix with trace 1
 * @throws Error if matrix is invalid or has zero trace
 */
export declare function normalizeMatrix(matrix: ComplexMatrix): ComplexMatrix;
export declare function scaleMatrix(matrix: ComplexMatrix, scalar: Complex): ComplexMatrix;
/**
 * Checks if a matrix is Hermitian (self-adjoint)
 *
 * @param matrix Input matrix
 * @param tolerance Numerical tolerance for comparison
 * @returns true if matrix is Hermitian
 * @throws Error if matrix is invalid or non-square
 */
export declare function isHermitian(matrix: ComplexMatrix, tolerance?: number): boolean;
/**
 * Checks if a matrix is unitary
 *
 * @param matrix Input matrix
 * @param tolerance Numerical tolerance for comparison
 * @returns true if matrix is unitary
 * @throws Error if matrix is invalid or non-square
 */
export declare function isUnitary(matrix: ComplexMatrix, tolerance?: number): boolean;
/**
 * Orthogonalizes a set of state vectors using modified Gram-Schmidt process
 *
 * This function provides a convenient wrapper around the internal degenerate
 * eigenvector orthogonalization for use with IStateVector objects. It:
 * 1. Converts IStateVector objects to ComplexMatrix format
 * 2. Groups vectors by eigenvalue (assumes all have same eigenvalue)
 * 3. Applies the validated orthogonalization algorithm
 * 4. Converts back to IStateVector objects
 *
 * Useful for:
 * - Orthogonalizing intertwiner basis states
 * - Processing degenerate quantum states
 * - Ensuring orthonormal bases in quantum calculations
 *
 * @param stateVectors - Array of state vectors to orthogonalize
 * @param precision - Numerical threshold for orthogonality (default: 1e-10)
 * @returns Array of orthogonalized state vectors
 * @throws Error if state vectors have different dimensions
 */
export declare function orthogonalizeStateVectors(stateVectors: IStateVector[], precision?: number): IStateVector[];