Analytic special functions, finite ladder helpers, and q-analogs. More...

#include <complex.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "oakfield/field.h"

Include dependency graph for special_functions.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	SimComplexFloat
	Fallback ABI-compatible complex float if not in field.h. More...

struct	SimComplexDouble
	Explicit in-memory representation for a complex double scalar (re, im) More...

struct	SimSpecialEvalReport
	Structured report describing why a special-function helper failed. More...

Macros
#define	SIM_DIAGNOSTICS 0

#define	SIM_DIGAMMA_SQUARE_DEFORMATION_DEFAULT 0.25

Typedefs
typedef enum SimDigammaBackend	SimDigammaBackend
	Backend choice for digamma/trigamma evaluation.

Enumerations
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 }
	Backend choice for digamma/trigamma evaluation. More...

Functions
Digamma daily drivers (real, double)
ψ(x) using Stirling tail truncated after N=12,7,5 Bernoulli pairs. Note Reflection + recurrence handle x<=0; asymptotics for large x. See also DLMF 5.11 & 5.15 for expansions and reflection.
double	sim_digamma_f64_12 (double x)

double	sim_digamma_f64_7 (double x)

double	sim_digamma_f64_5 (double x)

Digamma daily drivers (real, float)
float	sim_digamma_f32_12 (float x)

float	sim_digamma_f32_7 (float x)

float	sim_digamma_f32_5 (float x)

Digamma (complex, double) — analytic continuation
SimComplexDouble	sim_digamma_c64_12 (SimComplexDouble z)

SimComplexDouble	sim_digamma_c64_7 (SimComplexDouble z)

SimComplexDouble	sim_digamma_c64_5 (SimComplexDouble z)

Digamma (complex, float) — analytic continuation
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)
	Speedy Mortici-style digamma (complex, double).

SimComplexFloat	sim_digamma_c32_mortici (SimComplexFloat z)

double	sim_digamma_f64_tail (double x, double tol)
	Digamma with adaptive tail: run Bernoulli series until \|next term\| < tol.

SimComplexDouble	sim_digamma_c64_tail (SimComplexDouble z, double tol)
	Complex digamma with adaptive tail.

double	sim_digamma_f64_mortici (double x)
	Speedy Mortici-style digamma (real, double).

float	sim_digamma_f32_mortici (float x)
	Speedy Mortici-style digamma (real, float).

double	sim_special_digamma (double x)

SimComplexDouble	sim_special_digamma_complex (SimComplexDouble z)

double	sim_digamma_square_base_real (double amplitude, double inner_radians, SimDigammaBackend backend, double tolerance)
	Legacy digamma-square base with the quarter-shift deformation.

double	sim_digamma_square_base_deformed_real (double amplitude, double a, double inner_radians, SimDigammaBackend backend, double tolerance)
	Deformable digamma-square base using notebook-style shift parameter a.

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 daily drivers (real, double)
double	sim_trigamma_f64_12 (double x)

double	sim_trigamma_f64_7 (double x)

double	sim_trigamma_f64_5 (double x)

Trigamma daily drivers (real, float)
float	sim_trigamma_f32_12 (float x)

float	sim_trigamma_f32_7 (float x)

float	sim_trigamma_f32_5 (float x)

Trigamma (complex, double) — analytic continuation
SimComplexDouble	sim_trigamma_c64_12 (SimComplexDouble z)

SimComplexDouble	sim_trigamma_c64_7 (SimComplexDouble z)

SimComplexDouble	sim_trigamma_c64_5 (SimComplexDouble z)

Tetragamma daily drivers (real, double)
double	sim_tetragamma_f64_12 (double x)

double	sim_tetragamma_f64_7 (double x)

double	sim_tetragamma_f64_5 (double x)

Tetragamma daily drivers (real, float)
float	sim_tetragamma_f32_12 (float x)

float	sim_tetragamma_f32_7 (float x)

float	sim_tetragamma_f32_5 (float x)

Tetragamma (complex, double) — analytic continuation
SimComplexDouble	sim_tetragamma_c64_12 (SimComplexDouble z)

SimComplexDouble	sim_tetragamma_c64_7 (SimComplexDouble z)

SimComplexDouble	sim_tetragamma_c64_5 (SimComplexDouble z)

Safe classical special-function helpers with fallback hooks
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)

Experimental safe q-number helpers with fallback hooks
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)

Experimental safe q-zeta helpers with fallback hooks
SimResult	sim_q_zeta_safe (double s, double a, double q, SimSpecialFallbackFn fallback, void userdata, SimSpecialEvalReport report, double *out_value)

Experimental safe q-digamma helpers with fallback hooks
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)

Trigamma (complex, float) — analytic continuation
#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

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)
	Trigamma with adaptive tail (real).

SimComplexDouble	sim_trigamma_c64_tail (SimComplexDouble z, double tol)
	Trigamma with adaptive tail (complex).

double	sim_trigamma_f64_mortici (double x)
	Speedy trigamma (real, double): ψ₁(x) ≈ 1/x + 1/(2x²) + 1/(6x³) for x>0, with reflection+recurrence elsewhere. Matches asymptotic coefficients to O(x⁻³).

float	sim_trigamma_f32_mortici (float x)
	Speedy trigamma (real, float).

double	sim_special_trigamma (double x)

SimComplexDouble	sim_special_trigamma_complex (SimComplexDouble z)

Tetragamma (complex, float) — analytic continuation
enum	SimSpecialFault { SIM_SPECIAL_FAULT_NONE = 0 , SIM_SPECIAL_FAULT_DOMAIN , SIM_SPECIAL_FAULT_SINGULARITY , SIM_SPECIAL_FAULT_ITERATION_LIMIT , SIM_SPECIAL_FAULT_NUMERIC }
	Fault categories for special-function helpers when evaluation fails. More...

typedef enum SimSpecialFault	SimSpecialFault
	Fault categories for special-function helpers when evaluation fails.

typedef struct SimSpecialEvalReport	SimSpecialEvalReport
	Structured report describing why a special-function helper failed.

typedef SimResult(*	SimSpecialFallbackFn) (void userdata, const SimSpecialEvalReport report, SimComplexDouble *value_out)
	Callback signature used to provide fallback values on failure.

SimComplexFloat	sim_tetragamma_c32_12 (SimComplexFloat z)

SimComplexFloat	sim_tetragamma_c32_7 (SimComplexFloat z)

SimComplexFloat	sim_tetragamma_c32_5 (SimComplexFloat z)

double	sim_special_tetragamma (double x)

SimComplexDouble	sim_special_tetragamma_complex (SimComplexDouble z)

double	sim_ghn_HK (double a, int K)
	Generalized harmonic ladder H_K(a) = Σ_{k=0}^{K-1} 1/(a+k).

double	sim_ghn_HK_d1 (double a, int K)
	First derivative H'_K(a) = ψ₁(a+K) − ψ₁(a). (Negative for a>0,K>0.)

double	sim_ghn_HK_d2 (double a, int K)
	Second derivative H''_K(a) = ψ₂(a+K) − ψ₂(a). (Positive for a>0,K>0.)

SimComplexDouble	sim_ghn_HK_complex (SimComplexDouble a, int K)
	Complex generalized harmonic ladder using ψ difference.

SimComplexDouble	sim_ghn_HK_d1_complex (SimComplexDouble a, int K)
	Complex first derivative using trigamma difference.

SimComplexDouble	sim_ghn_HK_d2_complex (SimComplexDouble a, int K)
	Complex second derivative using tetragamma difference.

double	sim_hyperexp_phi (double lambda, double epsilon, int K)
	Finite ladder helper φ(λ,ε;K) = Σ_{k=0}^{K-1} λ/(λ+ε+k).

double	sim_hyperexp_phi_deriv (double lambda, double epsilon, int K)
	∂φ/∂λ = [ψ(λ+ε+K) − ψ(λ+ε)] + λ[ψ₁(λ+ε+K) − ψ₁(λ+ε)].

SimComplexDouble	sim_hyperexp_phi_complex (SimComplexDouble lambda, SimComplexDouble epsilon, int K)
	Complex φ using the same ψ-difference identity.

double	sim_qhyperexp_phi (double lambda, double epsilon, int K, double q)
	q-deformed φ_q(λ,ε;K,q) := Σ_{k=0}^{K-1} λ / (λ + ε q^k).

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)
	Experimental complex q-φ and derivative.

SimComplexDouble	sim_qhyperexp_phi_deriv_complex (SimComplexDouble lambda, SimComplexDouble epsilon, int K, double q)

double	sim_q_number (double x, double q)
	Experimental Jackson q-number [x]_q = (1 - q^x) / (1 - q) with stable q→1 limit.

SimComplexDouble	sim_q_number_complex (SimComplexDouble z, double q)
	Experimental complex Jackson q-number for SimComplexDouble argument.

double	sim_q_zeta (double s, double a, double q)
	Experimental q-zeta (Hurwitz-style) ζ_q(s, a) = Σ_{n>=0} q^{(n+a)(s-1)} / [n+a]_q^s.

double	sim_q_digamma (double x, double q)
	Experimental q-digamma ψ_q(z) with analytic continuation via Jackson series.

SimComplexDouble	sim_q_digamma_complex (SimComplexDouble z, double q)
	Experimental complex q-digamma ψ_q(z) for SimComplexDouble argument.

const char *	sim_special_fault_name (SimSpecialFault fault)
	Convert a fault enum to a human-readable string.

Detailed Description

Analytic special functions, finite ladder helpers, and q-analogs.

Implementations:

Real & complex, float & double precision.
Daily drivers: fixed 12/7/5-term Stirling tails.
Accuracy-driven: tail runs until |next term| < tol.
Speedy: Mortici-style log-shift rational approximants (few flops).
Finite ladder φ and q-φ via digamma/trigamma differences.

Math references:

Asymptotic expansions and reflection: NIST DLMF §5.11 and §5.15.
Reflection identities: ψ(1−z)−ψ(z)=π cot(πz), ψ₁(1−z)+ψ₁(z)=π² csc²(πz).

Implementation notes:

Real reflection avoids libm trig: custom sinpi/cospi via quadrant reduction and polynomial kernels with FMA.
Complex path uses stable exponentials for sin(πz)/cos(πz) to avoid overflow.
Optional MPFR/MPC backends (define SIM_HAVE_MPFR/SIM_HAVE_MPC) provide true arbitrary precision; otherwise, "AP" variants run the Bernoulli tail to tolerance in long double / double complex.

Enumeration Type Documentation

◆ SimDigammaBackend

enum SimDigammaBackend

Backend choice for digamma/trigamma evaluation.

Enumerator
SIM_DIGAMMA_BACKEND_12_TAIL	12-term Stirling tail digamma/trigamma.
SIM_DIGAMMA_BACKEND_7_TAIL	7-term Stirling tail digamma/trigamma.
SIM_DIGAMMA_BACKEND_5_TAIL	5-term Stirling tail digamma/trigamma.
SIM_DIGAMMA_BACKEND_ADAPTIVE	Adaptive-tail digamma/trigamma.
SIM_DIGAMMA_BACKEND_MORTICI	Mortici speedy digamma/trigamma.

◆ SimSpecialFault

enum SimSpecialFault

Fault categories for special-function helpers when evaluation fails.

Enumerator
SIM_SPECIAL_FAULT_NONE	No error.
SIM_SPECIAL_FAULT_DOMAIN	Argument outside supported domain.
SIM_SPECIAL_FAULT_SINGULARITY	Encountered pole / denominator singularity.
SIM_SPECIAL_FAULT_ITERATION_LIMIT	Failed to converge within iteration budget.
SIM_SPECIAL_FAULT_NUMERIC	General numeric breakdown (overflow/NaN).

Function Documentation

◆ sim_digamma_c64_mortici()

SimComplexDouble sim_digamma_c64_mortici ( SimComplexDouble z )

Speedy Mortici-style digamma (complex, double).

Note: Reflection + recurrence for stability; mirrors the real Mortici coefficients.

◆ sim_digamma_c64_tail()

SimComplexDouble sim_digamma_c64_tail	(	SimComplexDouble	z,
		double	tol
	)

Complex digamma with adaptive tail.

Parameters

z	Complex argument (double complex ABI).
tol	Absolute tolerance on next Bernoulli term.

◆ sim_digamma_f64_mortici()

double sim_digamma_f64_mortici ( double x )

Speedy Mortici-style digamma (real, double).

For x>0 uses ψ(x) ≈ log(x + δ) − 1/(2x) with δ = 1/2 + 1/(24x) − 1/(48x²) + 23/(5760 x³), matching terms through O(x⁻⁴) in the asymptotics; reflection+recurrence elsewhere.

Note: Designed for throughput over last‑bit accuracy; use sim_digamma_f64_12 for best accuracy.

◆ sim_digamma_f64_tail()

double sim_digamma_f64_tail	(	double	x,
		double	tol
	)

Digamma with adaptive tail: run Bernoulli series until |next term| < tol.

Parameters

x	Real argument (double).
tol	Absolute tolerance on next Bernoulli term (e.g., 1e-16).

Returns: ψ(x) with tail stopped adaptively.

◆ sim_digamma_square_base_deformed_real()

double sim_digamma_square_base_deformed_real	(	double	amplitude,
		double	a,
		double	inner_radians,
		SimDigammaBackend	backend,
		double	tolerance
	)

Deformable digamma-square base using notebook-style shift parameter a.

Computes A * (1 + (cos(inner) - cos(2*pi*a)) * (psi(a+u) - psi(1-a+u)) / pi), where inner = 2*pi*u.

◆ sim_digamma_square_base_real()

double sim_digamma_square_base_real	(	double	amplitude,
		double	inner_radians,
		SimDigammaBackend	backend,
		double	tolerance
	)

Legacy digamma-square base with the quarter-shift deformation.

Parameters

amplitude	Output amplitude multiplier.
inner_radians	Normalized carrier sample u.
backend	Digamma backend selector.
tolerance	Adaptive-tail tolerance when backend=adaptive.

◆ sim_ghn_HK()

double sim_ghn_HK	(	double	a,
		int	K
	)

Generalized harmonic ladder H_K(a) = Σ_{k=0}^{K-1} 1/(a+k).

Analytic continuation: H_K(a) = ψ(a+K) − ψ(a). For large a with small K, uses a stable asymptotic difference (log1p + Bernoulli tail) to avoid cancellation.

Parameters

a	Real shift (typically a = λ + ε). Requires a>0.
K	Ladder depth (K>=0). For K==0 returns 0.

◆ sim_hyperexp_phi()

double sim_hyperexp_phi	(	double	lambda,
		double	epsilon,
		int	K
	)

Finite ladder helper φ(λ,ε;K) = Σ_{k=0}^{K-1} λ/(λ+ε+k).

Numerically stabilized via ψ-difference: φ = λ [ ψ(λ+ε+K) − ψ(λ+ε) ] (valid ∀ complex λ,ε with poles excluded). This removes inner loops, improves accuracy, and exposes derivatives.

◆ sim_q_number()

double sim_q_number	(	double	x,
		double	q
	)

Experimental Jackson q-number [x]_q = (1 - q^x) / (1 - q) with stable q→1 limit.

Warning: Experimental API. q-analog helpers are included for exploration. Their input-domain checks, convergence limits, fallback behavior, and precision guarantees may change before they are declared stable.

◆ sim_q_zeta()

double sim_q_zeta	(	double	s,
		double	a,
		double	q
	)

Experimental q-zeta (Hurwitz-style) ζ_q(s, a) = Σ_{n>=0} q^{(n+a)(s-1)} / [n+a]_q^s.

Note: Convergent for q∈(0,1) and s>1 with a>0. Returns NAN outside this domain.

◆ sim_qhyperexp_phi()

double sim_qhyperexp_phi	(	double	lambda,
		double	epsilon,
		int	K,
		double	q
	)

q-deformed φ_q(λ,ε;K,q) := Σ_{k=0}^{K-1} λ / (λ + ε q^k).

A geometric (q-analogue) ladder; derivative wrt λ: ∂φ_q/∂λ = Σ ε q^k / (λ + ε q^k)^2.

Note: Choose q∈(0,1) for decaying ladder; q>1 allowed but can amplify roundoff.

Warning: Experimental API. q-method domains, convergence behavior, and fallback policy may change before the math surface is stable.

◆ sim_qhyperexp_phi_complex()

SimComplexDouble sim_qhyperexp_phi_complex	(	SimComplexDouble	lambda,
		SimComplexDouble	epsilon,
		int	K,
		double	q
	)

Experimental complex q-φ and derivative.

q-method domains, convergence behavior, and fallback policy may change before the math surface is stable.

◆ sim_trigamma_c64_tail()

SimComplexDouble sim_trigamma_c64_tail	(	SimComplexDouble	z,
		double	tol
	)

Trigamma with adaptive tail (complex).

Parameters

z	Complex argument (double ABI).
tol	Absolute tolerance on next Bernoulli term.

◆ sim_trigamma_f64_tail()

double sim_trigamma_f64_tail	(	double	x,
		double	tol
	)

Trigamma with adaptive tail (real).

Parameters

x	Real argument (double).
tol	Absolute tolerance on next Bernoulli term.

Classes

Macros

Typedefs

Enumerations

Functions

Trigamma (complex, float) — analytic continuation

Tetragamma (complex, float) — analytic continuation

Detailed Description

Enumeration Type Documentation

◆ SimDigammaBackend

◆ SimSpecialFault

Function Documentation

◆ sim_digamma_c64_mortici()

◆ sim_digamma_c64_tail()

◆ sim_digamma_f64_mortici()

◆ sim_digamma_f64_tail()

◆ sim_digamma_square_base_deformed_real()

◆ sim_digamma_square_base_real()

◆ sim_ghn_HK()

◆ sim_hyperexp_phi()

◆ sim_q_number()

◆ sim_q_zeta()

◆ sim_qhyperexp_phi()

◆ sim_qhyperexp_phi_complex()

◆ sim_trigamma_c64_tail()

◆ sim_trigamma_f64_tail()