Source code for matrix_toolkit.pde.equations.helmholtz

"""
Helmholtz equation: -Δu - k²u = f
"""

import numpy as np
from scipy import sparse
from typing import Dict, Any

from matrix_toolkit.pde.base import BasePDEEquation
from matrix_toolkit.pde.config import PDEConfig  




class HelmholtzEquation(BasePDEEquation):
    """
    The Helmholtz equation:
    
    .. math::
    
        -\Delta u - k^2 u = f
    
    This equation arises in wave propagation, acoustics, and electromagnetics.
    
    Examples:
        >>> config = PDEConfig(
        ...     dimension=2,
        ...     mesh_size=64,
        ...     coefficients={'wavenumber': 10.0}
        ... )
        >>> eq = HelmholtzEquation(config)
        >>> A = eq.generate_matrix()
    """
    


    def get_operator_name(self) -> str:
        return "Helmholtz"

    


    def get_default_coefficients(self) -> Dict[str, Any]:
        return {
            'wavenumber': 1.0,  # k in -Δu - k²u
        }

    


    def generate_matrix(self) -> sparse.spmatrix:
        """Generate Helmholtz matrix"""
        coeffs = self.config.coefficients or self.get_default_coefficients()
        
        if self.config.random_params:
            coeffs = self.randomize_coefficients(self.config.random_seed)
        
        k = coeffs.get('wavenumber', 1.0)
        
        # Get Laplacian
        from matrix_toolkit.pde.equations.poisson import PoissonEquation
        
        laplacian_config = PDEConfig(
            dimension=self.config.dimension,
            domain=self.config.domain,
            mesh_size=self.config.mesh_size,
            boundary_condition=self.config.boundary_condition
        )
        
        poisson = PoissonEquation(laplacian_config)
        L = poisson.generate_matrix()
        
        # Helmholtz: -Δ - k²I
        n = self.config.total_dofs()
        I = sparse.eye(n, format='csr')
        
        A = L - (k**2) * I
        
        return A