special_functions.h

Go to the documentation of this file.

 
#ifndef SIM_MATH_SPECIAL_FUNCTIONS_H
#define SIM_MATH_SPECIAL_FUNCTIONS_H
 
#include <complex.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "oakfield/field.h" /* expected to define SimComplexDouble; we provide fallbacks below */
 
/* Compile-time diagnostics toggle: enable lightweight sampling of
 * special-function health metrics (reflection usage, Stirling tails, etc.).
 * Can be overridden by defining SIM_DIAGNOSTICS at compile time. */
#ifndef SIM_DIAGNOSTICS
#define SIM_DIAGNOSTICS 0
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef SIM_HAVE_SIMCOMPLEXFLOAT
typedef struct {
    float re, im; 
} SimComplexFloat;
#endif
 
#ifndef SIM_HAVE_SIMCOMPLEXDOUBLE
typedef struct {
    double re, im; 
} SimComplexDouble;
#endif
 
typedef enum SimDigammaBackend {
    SIM_DIGAMMA_BACKEND_12_TAIL  = 0, 
    SIM_DIGAMMA_BACKEND_7_TAIL   = 1, 
    SIM_DIGAMMA_BACKEND_5_TAIL   = 2, 
    SIM_DIGAMMA_BACKEND_ADAPTIVE = 3, 
    SIM_DIGAMMA_BACKEND_MORTICI  = 4, 
} SimDigammaBackend;
 
#ifndef SIM_DIGAMMA_SQUARE_DEFORMATION_DEFAULT
#define SIM_DIGAMMA_SQUARE_DEFORMATION_DEFAULT 0.25
#endif
 
/*==============================================================================
 *                           DIGAMMA (psi)
 *============================================================================*/
 
double sim_digamma_f64_12(double x);
double sim_digamma_f64_7(double x);
double sim_digamma_f64_5(double x);
float sim_digamma_f32_12(float x);
float sim_digamma_f32_7(float x);
float sim_digamma_f32_5(float x);
 
SimComplexDouble sim_digamma_c64_12(SimComplexDouble z);
SimComplexDouble sim_digamma_c64_7(SimComplexDouble z);
SimComplexDouble sim_digamma_c64_5(SimComplexDouble z);
 
SimComplexFloat sim_digamma_c32_12(SimComplexFloat z);
SimComplexFloat sim_digamma_c32_7(SimComplexFloat z);
SimComplexFloat sim_digamma_c32_5(SimComplexFloat z);
 
SimComplexDouble sim_digamma_c64_mortici(SimComplexDouble z);
SimComplexFloat  sim_digamma_c32_mortici(SimComplexFloat z);
 
double sim_digamma_f64_tail(double x, double tol);
 
SimComplexDouble sim_digamma_c64_tail(SimComplexDouble z, double tol);
 
double sim_digamma_f64_mortici(double x);
 
float sim_digamma_f32_mortici(float x);
 
/* Backward-compatible aliases matching your current API (default = 12-tail, double): */
double           sim_special_digamma(double x);
SimComplexDouble sim_special_digamma_complex(SimComplexDouble z);
 
/*==============================================================================
 *                      DIGAMMA WAVEFORM HELPERS (SQUARE)
 *============================================================================*/
 
double sim_digamma_square_base_real(double            amplitude,
                                    double            inner_radians,
                                    SimDigammaBackend backend,
                                    double            tolerance);
 
double sim_digamma_square_base_deformed_real(double            amplitude,
                                             double            a,
                                             double            inner_radians,
                                             SimDigammaBackend backend,
                                             double            tolerance);
 
SimComplexDouble sim_digamma_square_base_complex(double            amplitude,
                                                 SimComplexDouble  inner_radians,
                                                 SimDigammaBackend backend,
                                                 double            tolerance);
 
SimComplexDouble sim_digamma_square_base_deformed_complex(double            amplitude,
                                                          double            a,
                                                          SimComplexDouble  inner_radians,
                                                          SimDigammaBackend backend,
                                                          double            tolerance);
 
/*==============================================================================
 *                           TRIGAMMA (psi_1)
 *============================================================================*/
 
double sim_trigamma_f64_12(double x);
double sim_trigamma_f64_7(double x);
double sim_trigamma_f64_5(double x);
 
float sim_trigamma_f32_12(float x);
float sim_trigamma_f32_7(float x);
float sim_trigamma_f32_5(float x);
 
SimComplexDouble sim_trigamma_c64_12(SimComplexDouble z);
SimComplexDouble sim_trigamma_c64_7(SimComplexDouble z);
SimComplexDouble sim_trigamma_c64_5(SimComplexDouble z);
 
SimComplexFloat sim_trigamma_c32_12(SimComplexFloat z);
SimComplexFloat sim_trigamma_c32_7(SimComplexFloat z);
SimComplexFloat sim_trigamma_c32_5(SimComplexFloat z);
 
double sim_trigamma_f64_tail(double x, double tol);
 
SimComplexDouble sim_trigamma_c64_tail(SimComplexDouble z, double tol);
 
double sim_trigamma_f64_mortici(double x);
 
float sim_trigamma_f32_mortici(float x);
 
#define sim_digamma_f64_speedy sim_digamma_f64_mortici
#define sim_digamma_f32_speedy sim_digamma_f32_mortici
#define sim_trigamma_f64_speedy sim_trigamma_f64_mortici
#define sim_trigamma_f32_speedy sim_trigamma_f32_mortici
 
/* Backward-compatible aliases matching your current API (default = 12-tail, double): */
double           sim_special_trigamma(double x);
SimComplexDouble sim_special_trigamma_complex(SimComplexDouble z);
 
/*==============================================================================
 *                           TETRAGAMMA (psi_2)
 *============================================================================*/
 
double sim_tetragamma_f64_12(double x);
double sim_tetragamma_f64_7(double x);
double sim_tetragamma_f64_5(double x);
 
float sim_tetragamma_f32_12(float x);
float sim_tetragamma_f32_7(float x);
float sim_tetragamma_f32_5(float x);
 
SimComplexDouble sim_tetragamma_c64_12(SimComplexDouble z);
SimComplexDouble sim_tetragamma_c64_7(SimComplexDouble z);
SimComplexDouble sim_tetragamma_c64_5(SimComplexDouble z);
 
SimComplexFloat sim_tetragamma_c32_12(SimComplexFloat z);
SimComplexFloat sim_tetragamma_c32_7(SimComplexFloat z);
SimComplexFloat sim_tetragamma_c32_5(SimComplexFloat z);
 
/* Backward-compatible aliases */
double           sim_special_tetragamma(double x);
SimComplexDouble sim_special_tetragamma_complex(SimComplexDouble z);
 
/*==============================================================================
 *                 GENERALIZED HARMONIC NUMBERS (MGHN CORE)
 *============================================================================*/
 
double sim_ghn_HK(double a, int K);
 
double sim_ghn_HK_d1(double a, int K);
 
double sim_ghn_HK_d2(double a, int K);
 
SimComplexDouble sim_ghn_HK_complex(SimComplexDouble a, int K);
 
SimComplexDouble sim_ghn_HK_d1_complex(SimComplexDouble a, int K);
 
SimComplexDouble sim_ghn_HK_d2_complex(SimComplexDouble a, int K);
 
/*==============================================================================
 *                 FINITE LADDER φ AND q-DEFORMED φ
 *============================================================================*/
 
double sim_hyperexp_phi(double lambda, double epsilon, int K);
 
double sim_hyperexp_phi_deriv(double lambda, double epsilon, int K);
 
SimComplexDouble sim_hyperexp_phi_complex(SimComplexDouble lambda, SimComplexDouble epsilon, int K);
 
double sim_qhyperexp_phi(double lambda, double epsilon, int K, double q);
double sim_qhyperexp_phi_deriv(double lambda, double epsilon, int K, double q);
 
SimComplexDouble
sim_qhyperexp_phi_complex(SimComplexDouble lambda, SimComplexDouble epsilon, int K, double q);
SimComplexDouble
sim_qhyperexp_phi_deriv_complex(SimComplexDouble lambda, SimComplexDouble epsilon, int K, double q);
 
/*==============================================================================
 *                                Q-ANALOGS
 *============================================================================*/
 
double sim_q_number(double x, double q);
 
SimComplexDouble sim_q_number_complex(SimComplexDouble z, double q);
 
double sim_q_zeta(double s, double a, double q);
 
double sim_q_digamma(double x, double q);
 
SimComplexDouble sim_q_digamma_complex(SimComplexDouble z, double q);
 
#if SIM_DIAGNOSTICS
typedef struct SimSpecialDiagnosticsSnapshot {
    uint64_t reflection_count;         
    uint64_t recurrence_shift_samples; 
    double   max_recurrence_shift;     
    uint64_t stirling_tail_samples;    
    double   max_stirling_tail;        
    uint64_t pole_proximity_samples;   
    double   min_pole_distance;        
} SimSpecialDiagnosticsSnapshot;
 
void sim_special_diagnostics_snapshot(SimSpecialDiagnosticsSnapshot* out, bool reset);
#endif
 
typedef enum SimSpecialFault {
    SIM_SPECIAL_FAULT_NONE = 0,        
    SIM_SPECIAL_FAULT_DOMAIN,          
    SIM_SPECIAL_FAULT_SINGULARITY,     
    SIM_SPECIAL_FAULT_ITERATION_LIMIT, 
    SIM_SPECIAL_FAULT_NUMERIC          
} SimSpecialFault;
 
typedef struct SimSpecialEvalReport {
    SimSpecialFault  fault;           
    const char*      function;        
    SimComplexDouble input;           
    double           q_param;         
    double           aux_param;       
    double           exponent_param;  
    int              iteration_count; 
    double           residual;        
    double           tolerance;       
} SimSpecialEvalReport;
 
typedef SimResult (*SimSpecialFallbackFn)(void*                       userdata,
                                          const SimSpecialEvalReport* report,
                                          SimComplexDouble*           value_out);
 
const char* sim_special_fault_name(SimSpecialFault fault);
 
SimResult sim_digamma_safe(double                x,
                           SimSpecialFallbackFn  fallback,
                           void*                 userdata,
                           SimSpecialEvalReport* report,
                           double*               out_value);
 
SimResult sim_trigamma_safe(double                x,
                            SimSpecialFallbackFn  fallback,
                            void*                 userdata,
                            SimSpecialEvalReport* report,
                            double*               out_value);
 
SimResult sim_tetragamma_safe(double                x,
                              SimSpecialFallbackFn  fallback,
                              void*                 userdata,
                              SimSpecialEvalReport* report,
                              double*               out_value);
 
SimResult sim_hyperexp_phi_safe(double                lambda,
                                double                epsilon,
                                int                   K,
                                SimSpecialFallbackFn  fallback,
                                void*                 userdata,
                                SimSpecialEvalReport* report,
                                double*               out_value);
 
SimResult sim_hyperexp_phi_deriv_safe(double                lambda,
                                      double                epsilon,
                                      int                   K,
                                      SimSpecialFallbackFn  fallback,
                                      void*                 userdata,
                                      SimSpecialEvalReport* report,
                                      double*               out_value);
 
SimResult sim_q_number_safe(double                x,
                            double                q,
                            SimSpecialFallbackFn  fallback,
                            void*                 userdata,
                            SimSpecialEvalReport* report,
                            double*               out_value);
 
SimResult sim_q_number_complex_safe(SimComplexDouble      z,
                                    double                q,
                                    SimSpecialFallbackFn  fallback,
                                    void*                 userdata,
                                    SimSpecialEvalReport* report,
                                    SimComplexDouble*     out_value);
 
SimResult sim_q_zeta_safe(double                s,
                          double                a,
                          double                q,
                          SimSpecialFallbackFn  fallback,
                          void*                 userdata,
                          SimSpecialEvalReport* report,
                          double*               out_value);
 
SimResult sim_q_digamma_safe(double                x,
                             double                q,
                             SimSpecialFallbackFn  fallback,
                             void*                 userdata,
                             SimSpecialEvalReport* report,
                             double*               out_value);
 
SimResult sim_q_digamma_complex_safe(SimComplexDouble      z,
                                     double                q,
                                     SimSpecialFallbackFn  fallback,
                                     void*                 userdata,
                                     SimSpecialEvalReport* report,
                                     SimComplexDouble*     out_value);
 
/*==============================================================================
 *                     OPTIONAL ARBITRARY PRECISION (MPFR/MPC)
 *============================================================================*/
 
#ifdef SIM_HAVE_MPFR
#include <mpfr.h>
void sim_digamma_mpfr(mpfr_t y, const mpfr_t x, const mpfr_t tol);
 
void sim_trigamma_mpfr(mpfr_t y, const mpfr_t x, const mpfr_t tol);
 
#ifdef SIM_HAVE_MPC
#include <mpc.h>
void sim_digamma_mpc(mpc_t y, const mpc_t z, const mpfr_t tol);
void sim_trigamma_mpc(mpc_t y, const mpc_t z, const mpfr_t tol);
#endif
#endif /* SIM_HAVE_MPFR */
 
#ifdef __cplusplus
}
#endif
#endif /* SIM_MATH_SPECIAL_FUNCTIONS_H */