mathhook-core 0.2.0

//! Special Function and Polynomial Properties
//!
//! Comprehensive mathematical properties for advanced special functions (gamma, bessel, zeta)
//! and polynomial families (Legendre, Hermite, Laguerre, Chebyshev, etc.).
//! Following SymPy's approach but optimized for performance.

use super::rules::{
    AntiderivativeRule, EvaluationMethod, RecurrenceRule, SpecialValue, ThreeTermRecurrence,
};
use crate::core::Expression;

/// Symbolic polynomial expander for function intelligence
///
/// Provides symbolic expansion capability for orthogonal polynomials,
/// enabling conversion from recurrence-based representation to explicit
/// polynomial forms in the Expression system.
#[derive(Debug, Clone, Copy)]
pub enum SymbolicExpander {
    /// Custom expansion function
    ///
    /// Takes polynomial degree n and returns explicit symbolic expression
    Custom(fn(usize) -> Expression),
}

/// Special function properties (gamma, bessel, zeta, etc.)
///
/// Comprehensive mathematical properties for advanced special functions
/// following SymPy's approach but optimized for performance.
///
/// **Note**: Evaluation is handled by direct dispatch through
/// `Expression::evaluate_function_dispatch()` for performance.
/// This struct stores only mathematical properties, not evaluation logic.
#[derive(Clone)]
pub struct SpecialProperties {
    /// Quick derivative check
    pub has_derivative: bool,

    /// Quick antiderivative check
    pub has_antiderivative: bool,

    /// Antiderivative rule (if known)
    pub antiderivative_rule: Option<AntiderivativeRule>,

    /// Recurrence relations for symbolic computation
    /// Examples: Γ(n+1) = n·Γ(n), J_{n+1} = (2n/x)J_n - J_{n-1}
    pub recurrence_relations: Vec<RecurrenceRule>,

    /// Differential equation the function satisfies
    /// Examples: Bessel DE, hypergeometric DE
    pub differential_equation: Option<DifferentialEquation>,

    /// Special values for exact computation
    pub special_values: Vec<SpecialValue>,

    /// Asymptotic behavior for large arguments
    pub asymptotic_behavior: Option<AsymptoticData>,

    /// Wolfram Language function name
    /// Used for Wolfram formatting without hardcoded matches
    /// Example: "gamma" → "Gamma", "zeta" → "Zeta"
    pub wolfram_name: Option<&'static str>,
}

impl std::fmt::Debug for SpecialProperties {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SpecialProperties")
            .field("has_derivative", &self.has_derivative)
            .field("has_antiderivative", &self.has_antiderivative)
            .field("antiderivative_rule", &self.antiderivative_rule)
            .field("recurrence_relations", &self.recurrence_relations)
            .field("differential_equation", &self.differential_equation)
            .field("special_values", &self.special_values)
            .field("asymptotic_behavior", &self.asymptotic_behavior)
            .field("wolfram_name", &self.wolfram_name)
            .finish()
    }
}

/// Polynomial function properties (legendre, hermite, laguerre, etc.)
///
/// Comprehensive properties for orthogonal polynomials and polynomial families
/// with focus on computational efficiency and mathematical correctness.
///
/// **Note**: Evaluation is handled by direct dispatch through
/// `Expression::evaluate_function_dispatch()` for performance.
/// This struct stores only mathematical properties, not evaluation logic.
#[derive(Clone)]
pub struct PolynomialProperties {
    /// Polynomial family classification
    pub family: PolynomialFamily,

    /// Three-term recurrence relation
    /// Examples: P_{n+1} = ((2n+1)x P_n - n P_{n-1})/(n+1)
    pub recurrence: ThreeTermRecurrence,

    /// Orthogonality properties (if applicable)
    pub orthogonality: Option<OrthogonalityData>,

    /// Rodrigues' formula (if available)
    /// Examples: P_n(x) = (1/2^n n!) d^n/dx^n (x²-1)^n
    pub rodrigues_formula: Option<RodriguesFormula>,

    /// Generating function
    /// Examples: 1/√(1-2xt+t²) = Σ P_n(x) t^n
    pub generating_function: Option<GeneratingFunction>,

    /// Special values and boundary conditions
    pub special_values: Vec<SpecialValue>,

    /// Computational method for evaluation
    pub evaluation_method: EvaluationMethod,

    /// Symbolic expansion method for intelligence-driven computation
    ///
    /// Converts polynomial from recurrence-based representation to explicit
    /// symbolic expression. This enables algebraic manipulation and simplification
    /// of polynomial expressions in the Expression system.
    pub symbolic_expander: Option<SymbolicExpander>,

    /// Antiderivative rule (for polynomial integration)
    /// All polynomials are integrable, so this is always Some(...)
    pub antiderivative_rule: AntiderivativeRule,

    /// Wolfram Language function name
    /// Used for Wolfram formatting without hardcoded matches
    /// Example: "legendre_p" → "LegendreP", "hermite_h" → "HermiteH"
    pub wolfram_name: Option<&'static str>,
}

impl std::fmt::Debug for PolynomialProperties {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PolynomialProperties")
            .field("family", &self.family)
            .field("recurrence", &self.recurrence)
            .field("orthogonality", &self.orthogonality)
            .field("rodrigues_formula", &self.rodrigues_formula)
            .field("generating_function", &self.generating_function)
            .field("special_values", &self.special_values)
            .field("evaluation_method", &self.evaluation_method)
            .field("symbolic_expander", &self.symbolic_expander)
            .field("antiderivative_rule", &self.antiderivative_rule)
            .field("wolfram_name", &self.wolfram_name)
            .finish()
    }
}

/// Polynomial family classification
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum PolynomialFamily {
    Legendre,
    Hermite,
    Laguerre,
    Chebyshev,
    Jacobi,
    Gegenbauer,
}

/// Orthogonality properties for polynomial families
#[derive(Debug, Clone)]
pub struct OrthogonalityData {
    /// Weight function w(x)
    pub weight_function: Expression,

    /// Orthogonality interval [a, b]
    pub interval: (Expression, Expression),

    /// Normalization constant
    pub norm_squared: Expression,
}

/// Rodrigues' formula for polynomial construction
#[derive(Debug, Clone)]
pub struct RodriguesFormula {
    /// Formula template
    pub formula: String,

    /// Normalization constant
    pub normalization: Expression,

    /// Weight function
    pub weight_function: Expression,
}

/// Generating function for polynomial families
#[derive(Debug, Clone)]
pub struct GeneratingFunction {
    /// Generating function expression
    pub function: Expression,

    /// Type: ordinary or exponential
    pub gf_type: GeneratingFunctionType,
}

/// Types of generating functions
#[derive(Debug, Clone, Copy)]
pub enum GeneratingFunctionType {
    Ordinary,
    Exponential,
}

/// Differential equation representation
#[derive(Debug, Clone)]
pub struct DifferentialEquation {
    /// Order of the differential equation
    pub order: usize,

    /// Equation in standard form
    pub equation: String,

    /// Coefficients (if polynomial)
    pub coefficients: Vec<Expression>,
}

/// Asymptotic behavior data
#[derive(Debug, Clone)]
pub struct AsymptoticData {
    /// Behavior as x → ∞
    pub as_x_to_infinity: String,

    /// Behavior as x → 0
    pub as_x_to_zero: String,

    /// Leading term coefficient
    pub leading_coefficient: Expression,
}