ts-quantum/dist/operators/hamiltonian.js

TypeScript library for quantum mechanics calculations and utilities

"use strict";
/**
 * Quantum Hamiltonian Implementation
 *
 * This module provides a comprehensive implementation of quantum Hamiltonians,
 * which are the fundamental operators representing the total energy of quantum
 * systems. The Hamiltonian determines:
 * - System energy levels (eigenvalues)
 * - Stationary states (eigenvectors)
 * - Time evolution (through Schrödinger equation)
 *
 * Key features:
 * - Custom and predefined Hamiltonian types
 * - Time evolution generation
 * - Energy expectation calculation
 * - Support for common physical systems:
 *   * Spin-1/2 in magnetic field
 *   * Heisenberg spin chains
 *   * Harmonic oscillators
 *   * Custom interactions
 *
 * Mathematical form:
 * H = Σᵢ cᵢOᵢ where:
 * - cᵢ are complex coefficients
 * - Oᵢ are quantum operators
 *
 * @module quantum/hamiltonian
 */
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    var desc = Object.getOwnPropertyDescriptor(m, k);
    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
      desc = { enumerable: true, get: function() { return m[k]; } };
    }
    Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
    Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
    o["default"] = v;
});
var __importStar = (this && this.__importStar) || function (mod) {
    if (mod && mod.__esModule) return mod;
    var result = {};
    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
    __setModuleDefault(result, mod);
    return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.Hamiltonian = void 0;
const operator_1 = require("./operator");
const validation_1 = require("../utils/validation");
const matrixOperations_1 = require("../utils/matrixOperations");
const gates_1 = require("./gates");
const composite_1 = require("../states/composite");
const matrixOperations_2 = require("../utils/matrixOperations");
const math = __importStar(require("mathjs"));
/**
 * Core Hamiltonian class representing quantum system energy operators
 *
 * The Hamiltonian is the fundamental operator in quantum mechanics that:
 * 1. Determines the total energy of the system
 * 2. Generates time evolution through Schrödinger's equation
 * 3. Defines the system's energy eigenstates
 *
 * Features:
 * - Constructs Hamiltonians from operator terms
 * - Validates Hermiticity (optional)
 * - Generates time evolution operators
 * - Computes energy expectations
 * - Supports both time-dependent and time-independent cases
 *
 * Physical Significance:
 * - Eigenvalues represent possible energy measurements
 * - Eigenvectors represent stationary states
 * - Expectation values give average energy
 * - Time evolution U(t) = exp(-iHt/ħ) describes dynamics
 *
 * @extends MatrixOperator
 */
class Hamiltonian extends operator_1.MatrixOperator {
    constructor(dimension, terms, hamiltonianType = 'custom', timeDependent = false, requireHermitian = false) {
        (0, validation_1.validatePosDim)(dimension);
        // Validate Hermiticity of individual terms and result if required
        if (requireHermitian) {
            for (const term of terms) {
                if (!term || !term.operator) {
                    throw new Error('Invalid term in Hamiltonian');
                }
                const termMatrix = term.operator.toMatrix();
                try {
                    if (!(0, matrixOperations_2.isHermitian)(termMatrix)) {
                        throw new Error('All terms must be Hermitian when requireHermitian is true');
                    }
                }
                catch (e) {
                    if (e instanceof Error) {
                        throw new Error(`Hermiticity check failed: ${e.message}`);
                    }
                    else {
                        throw new Error('Hermiticity check failed: Unknown error');
                    }
                }
                if (term.coefficient && Math.abs(term.coefficient.im) > 1e-10) {
                    throw new Error('All coefficients must be real when requireHermitian is true');
                }
            }
            // Also check the final matrix
            try {
                const matrix = terms.reduce((acc, term) => {
                    const termMatrix = term.operator.toMatrix();
                    const scaledTerm = (0, matrixOperations_1.scaleMatrix)(termMatrix, term.coefficient);
                    return acc.map((row, i) => row.map((elem, j) => math.add(elem, scaledTerm[i][j])));
                }, Array(dimension).fill(null).map(() => Array(dimension).fill(null).map(() => math.complex(0, 0))));
                if (!(0, matrixOperations_2.isHermitian)(matrix)) {
                    throw new Error('Combined Hamiltonian must be Hermitian when requireHermitian is true');
                }
            }
            catch (e) {
                if (e instanceof Error) {
                    throw new Error(`Hermiticity validation failed: ${e.message}`);
                }
                else {
                    throw new Error('Hermiticity validation failed: Unknown error');
                }
            }
        }
        // Initialize operator with sum of terms
        const matrix = terms.reduce((acc, term) => {
            const termMatrix = term.operator.toMatrix();
            const scaledTerm = (0, matrixOperations_1.scaleMatrix)(termMatrix, term.coefficient);
            return acc.map((row, i) => row.map((elem, j) => math.add(elem, scaledTerm[i][j])));
        }, Array(dimension).fill(null).map(() => Array(dimension).fill(null).map(() => math.complex(0, 0))));
        // Always use 'general' as the operator type, store Hamiltonian type separately
        super(matrix, 'general');
        this.hamiltonianType = hamiltonianType;
        this.terms = [...terms];
        this._timeDependent = timeDependent;
    }
    /**
     * Generates the quantum time evolution operator U(t) = exp(-iHt/ħ)
     *
     * The time evolution operator is fundamental in quantum mechanics:
     * - Transforms states from time t₀ to t: |ψ(t)⟩ = U(t-t₀)|ψ(t₀)⟩
     * - Preserves probability (unitary)
     * - Satisfies group properties (U(t₁)U(t₂) = U(t₁+t₂))
     *
     * Implementation:
     * 1. Validates time-independence
     * 2. Computes -iHt (using ħ = 1 units)
     * 3. Calculates matrix exponential
     * 4. Ensures unitarity
     *
     * @param time - Evolution time (in natural units)
     * @returns Unitary evolution operator U(t)
     * @throws Error for time-dependent Hamiltonians
     * @throws Error for invalid matrix structure
     */
    getEvolutionOperator(time) {
        if (this._timeDependent) {
            throw new Error('Time-dependent Hamiltonians require numerical integration');
        }
        // For a Hermitian matrix H, exp(-iHt) should be unitary
        // Create -iHt matrix
        const matrix = this.toMatrix();
        // Explicitly verify matrix
        if (!matrix || matrix.length === 0 || !matrix[0] || matrix[0].length === 0) {
            throw new Error('Invalid Hamiltonian matrix');
        }
        // Scale by -i*t (ħ = 1 units)
        const scaledMatrix = matrix.map(row => row.map(element => {
            // Multiply by -i*t
            return math.multiply(element, math.complex(0, -time));
        }));
        // Compute matrix exponential
        const evolutionMatrix = (0, matrixOperations_1.matrixExponential)(scaledMatrix);
        // Explicitly ensure it's properly formed
        const dim = this.dimension;
        for (let i = 0; i < dim; i++) {
            for (let j = 0; j < dim; j++) {
                if (!evolutionMatrix[i][j] || typeof evolutionMatrix[i][j].re !== 'number' ||
                    typeof evolutionMatrix[i][j].im !== 'number') {
                    evolutionMatrix[i][j] = math.complex(i === j ? 1 : 0, 0);
                }
            }
        }
        // Return as unitary operator
        return new operator_1.MatrixOperator(evolutionMatrix, 'unitary', false);
    }
    /**
     * Evolves a quantum state under this Hamiltonian for time t
     *
     * Implements Schrödinger equation evolution:
     * |ψ(t)⟩ = exp(-iHt/ħ)|ψ(0)⟩
     *
     * Process:
     * 1. Validates state dimension
     * 2. Computes evolution operator U(t)
     * 3. Applies U(t) to initial state
     * 4. Ensures normalization (corrects numerical errors)
     *
     * Physical meaning:
     * - Describes how quantum state changes with time
     * - Preserves total probability (norm = 1)
     * - Maintains quantum superposition
     *
     * @param state - Initial quantum state |ψ(0)⟩
     * @param time - Evolution time t
     * @returns Evolved state |ψ(t)⟩
     * @throws Error if dimensions don't match
     */
    evolveState(state, time) {
        if (state.dimension !== this.dimension) {
            throw new Error('State dimension does not match Hamiltonian dimension');
        }
        const U = this.getEvolutionOperator(time);
        // Apply evolution operator to state
        const evolvedState = U.apply(state);
        // Ensure the state is properly normalized
        // This step is important to correct for any numerical errors
        try {
            const norm = evolvedState.norm();
            if (norm > 1e-10 && Math.abs(norm - 1) > 1e-10) {
                return evolvedState.normalize();
            }
            return evolvedState;
        }
        catch (e) {
            // If normalization fails, ensure we still return a valid state
            console.error("Normalization error in evolveState:", e instanceof Error ? e.message : "Unknown error");
            return state; // Return original state if evolution fails
        }
    }
    /**
     * Computes the expectation value of energy for a given state
     *
     * The energy expectation value is:
     * ⟨E⟩ = ⟨ψ|H|ψ⟩
     *
     * Physical significance:
     * - Average energy in state |ψ⟩
     * - Real for physical (Hermitian) Hamiltonians
     * - Bounded by energy eigenvalues
     * - Constant for energy eigenstates
     *
     * @param state - Quantum state |ψ⟩
     * @returns Complex energy expectation value
     * @throws Error if dimensions don't match
     */
    expectationValue(state) {
        if (state.dimension !== this.dimension) {
            throw new Error('State dimension does not match Hamiltonian dimension');
        }
        const Hpsi = this.apply(state);
        return state.innerProduct(Hpsi);
    }
    /**
     * Creates a spin-1/2 Hamiltonian in a magnetic field
     *
     * Implements the Zeeman Hamiltonian:
     * H = B·σ = Bxσx + Byσy + Bzσz
     * where:
     * - B = (Bx, By, Bz) is the magnetic field vector
     * - σ = (σx, σy, σz) are the Pauli matrices
     *
     * Physical significance:
     * - Describes magnetic dipole in field
     * - Energy splitting ΔE = 2|B|
     * - Precession frequency ω = 2|B|
     * - Eigenstates align/anti-align with B
     *
     * @param magneticField - [Bx, By, Bz] field components
     * @returns Spin Hamiltonian operator
     *
     * @example
     * // Create Hamiltonian for field along z-axis
     * const H = Hamiltonian.createSpinHamiltonian([0, 0, 1]);
     */
    static createSpinHamiltonian(magneticField) {
        const [Bx, By, Bz] = magneticField;
        const terms = [
            {
                coefficient: math.complex(Bx, 0),
                operator: gates_1.PauliX
            },
            {
                coefficient: math.complex(By, 0),
                operator: gates_1.PauliY
            },
            {
                coefficient: math.complex(Bz, 0),
                operator: gates_1.PauliZ
            }
        ];
        return new Hamiltonian(2, terms, 'spin');
    }
    /**
     * Creates a Heisenberg interaction Hamiltonian for a spin chain
     *
     * Implements the Heisenberg model:
     * H = J Σᵢ Sᵢ·Sᵢ₊₁
     * where:
     * - J is the exchange coupling constant
     * - Sᵢ are spin operators at site i
     * - Sum runs over nearest neighbors
     *
     * The interaction term Sᵢ·Sᵢ₊₁ expands as:
     * Sᵢ·Sᵢ₊₁ = SxᵢSxᵢ₊₁ + SyᵢSyᵢ₊₁ + SzᵢSzᵢ₊₁
     *
     * Physical significance:
     * - Models magnetic interactions in materials
     * - J > 0: Ferromagnetic coupling (parallel spins favored)
     * - J < 0: Antiferromagnetic coupling (anti-parallel spins favored)
     * - Conserves total spin
     * - Supports quantum entanglement
     *
     * @param numSpins - Number of spins in the chain
     * @param coupling - Exchange coupling strength J
     * @returns Heisenberg Hamiltonian operator
     * @throws Error if numSpins < 2
     *
     * @example
     * // Create antiferromagnetic chain of 3 spins
     * const H = Hamiltonian.createHeisenbergHamiltonian(3, -1.0);
     */
    static createHeisenbergHamiltonian(numSpins, coupling) {
        if (numSpins < 2) {
            throw new Error('Heisenberg model requires at least 2 spins');
        }
        const terms = [];
        const coeff = math.complex(coupling, 0);
        const dimension = Math.pow(2, numSpins);
        // For each pair of neighboring spins
        for (let i = 0; i < numSpins - 1; i++) {
            // Create terms for σx⊗σx + σy⊗σy + σz⊗σz
            for (const pauli of [gates_1.PauliX, gates_1.PauliY, gates_1.PauliZ]) {
                // Create array of operators for tensor product
                const ops = Array(numSpins).fill(null).map(() => operator_1.MatrixOperator.identity(2));
                ops[i] = pauli;
                ops[i + 1] = pauli;
                try {
                    const op = (0, composite_1.composeOperators)(ops);
                    // Verify operator dimension
                    if (op.dimension !== dimension) {
                        throw new Error(`Operator dimension mismatch: expected ${dimension}, got ${op.dimension}`);
                    }
                    terms.push({
                        coefficient: coeff,
                        operator: op
                    });
                }
                catch (e) {
                    console.error(`Error creating Heisenberg term: ${e instanceof Error ? e.message : "Unknown error"}`);
                    // Create fallback identity term as placeholder
                    terms.push({
                        coefficient: math.complex(0, 0), // Zero coefficient
                        operator: operator_1.MatrixOperator.identity(dimension)
                    });
                }
            }
        }
        // Validate we have terms before creating Hamiltonian
        if (terms.length === 0) {
            throw new Error('Failed to create any valid terms for Heisenberg Hamiltonian');
        }
        return new Hamiltonian(dimension, terms, 'interaction');
    }
}
exports.Hamiltonian = Hamiltonian;
//# sourceMappingURL=hamiltonian.js.map