gr_special.h

Set res to \pi, Euler's constant \gamma, Catalan's constant G, Khinchin's constant K or Glaisher's constant A. Rings that do not contain the constant return GR_DOMAIN (gr_pi in \mathbb{Q}) or GR_UNABLE.

Set res to e^x, e^x - 1 (accurate for small x), 2^x or 10^x.

Sets res to e^{\pi i x}. For rational x this is a root of unity, computed exactly by qqbar.

Set res to the principal natural logarithm \log x, to \log(1 + x) (accurate for small x), or to the logarithms in base 2 and 10. GR_DOMAIN for x = 0.

Sets res to \log(x) / (\pi i), the inverse of gr_exp_pi_i on the principal branch.

Set res to the principal branch W_0(x) of the Lambert W function, or to the branch W_k(x) with index k given by the fmpz_t argument [Joh2017b].

Set res to \sin x, \cos x, both at once (gr_sin_cos sets res1 to the sine and res2 to the cosine), \tan x, \cot x, \sec x = 1/\cos x or \csc x = 1/\sin x. Poles give GR_DOMAIN.

The same functions evaluated at \pi x: \sin(\pi x) and so on. They are exact at integers and half-integers in ball arithmetic, and algebraic for rational x, which qqbar and ca compute exactly.

Set res to \operatorname{sinc}(x) = \sin(x)/x, respectively \sin(\pi x)/(\pi x), with the value 1 at x = 0.

Set res to the hyperbolic functions \sinh x, \cosh x (both at once for gr_sinh_cosh), \tanh x, \coth x, \operatorname{sech} x and \operatorname{csch} x.

Set res to \operatorname{asin} x, \operatorname{acos} x, \operatorname{atan} x, \operatorname{acot} x = \operatorname{atan}(1/x), \operatorname{asec} x = \operatorname{acos}(1/x) and \operatorname{acsc} x = \operatorname{asin}(1/x).

Sets res to \operatorname{atan2}(y, x), the argument of the point (x, y), where the first argument is y and the second x, as in C. Defined for real rings.

The inverse functions divided by \pi: \operatorname{asin}(x)/\pi and so on, which are rational for many algebraic x.

Set res to the inverse hyperbolic functions.

Set res to the factorial x! = \Gamma(x + 1). The vec version writes the first len factorials 0!, 1!, \ldots, (\mathit{len} - 1)! to the array res.

Set res to the reciprocal factorial 1/x! = 1/\Gamma(x+1), and the vec version to 1/0!, \ldots, 1/(\mathit{len} - 1)!; GR_DOMAIN if a factorial is not invertible in the ring.

Set res to the binomial coefficient \binom{x}{y}. The vec versions write \binom{x}{0}, \binom{x}{1}, \ldots, \binom{x}{\mathit{len}-1} to res. For a two-dimensional table (Pascal's triangle), gr_mat_pascal is faster than repeated calls.

Set res to the rising factorial x (x+1) \cdots (x+y-1) and the falling factorial x (x-1) \cdots (x-y+1), or their extensions \Gamma(x+y)/\Gamma(x) and \Gamma(x+1)/\Gamma(x-y+1) to non-integer y.

Set res to the gamma function \Gamma(x), its reciprocal 1/\Gamma(x) (entire, zero at the poles of \Gamma), the log-gamma function \log \Gamma(x) (the principal branch continuous away from the negative real axis) or the digamma function \psi(x) = \Gamma'(x)/\Gamma(x). gr_gamma returns GR_DOMAIN at the poles 0, -1, -2, \ldots. See The gamma function.

Sets res to the beta function B(x, y) = \Gamma(x) \Gamma(y) / \Gamma(x + y).

Set res to the Barnes G-function G(x), respectively its logarithm \log G(x).

Set res to the double factorial x!! = x (x - 2) (x - 4) \cdots, ending at 1 or 2.

Set res to the harmonic number H_x = \sum_{k=1}^{x} 1/k, or \psi(x+1) + \gamma for non-integer x.

Set res to the Bernoulli number B_n (with B_1 = -1/2). See bernoulli and Bernoulli numbers.

Set res to the Euler number E_n (the coefficients of \operatorname{sech}(t) = \sum E_n t^n / n!).

Set res to the Bernoulli polynomial B_n(x) or the Euler polynomial E_n(x). These methods are implemented for real and complex balls (arb_bernoulli_poly_ui, acb_bernoulli_poly_ui); other rings return GR_UNABLE.

Set res to the Fibonacci number F_n, with F_0 = 0 and F_1 = 1; gr_fib_fmpz accepts negative n, with F_{-n} = (-1)^{n+1} F_n.

Set res to the unsigned Stirling number of the first kind \left[{x \atop y}\right], the signed Stirling number of the first kind s(x, y), or the Stirling number of the second kind \left\{{x \atop y}\right\} (Stirling and Bell numbers).

Write the row S(x, 0), S(x, 1), \ldots, S(x, \mathit{len} - 1) of the respective Stirling numbers to res. For a two-dimensional table, gr_mat_stirling is faster than repeated calls.

Set res to the Bell number B_n, the number of partitions of a set of n elements (Stirling and Bell numbers).

Set res to the number of partitions p(n) of the integer n (Computing the partition function).

Set res to the error function \operatorname{erf}(x), the complementary error function \operatorname{erfc}(x) = 1 - \operatorname{erf}(x), the scaled complementary error function \operatorname{erfcx}(x) = e^{x^2} \operatorname{erfc}(x), or the imaginary error function \operatorname{erfi}(x) = -i \operatorname{erf}(ix).

Set res to the inverse error function and the inverse complementary error function, for real arguments in (-1, 1), respectively (0, 2).

Set res to the Fresnel integral S(x) = \int_0^x \sin(\pi t^2 / 2) \, dt or C(x) = \int_0^x \cos(\pi t^2 / 2) \, dt if normalized is nonzero, and to the unnormalised integrals \int_0^x \sin(t^2) \, dt and \int_0^x \cos(t^2) \, dt otherwise; gr_fresnel sets res1 to S and res2 to C.

Set res to the incomplete gamma functions with parameter s = x and argument z = y: if regularized is 0, the upper function \Gamma(s, z) = \int_z^\infty t^{s-1} e^{-t} \, dt and the lower function \gamma(s, z) = \int_0^z t^{s-1} e^{-t} \, dt; if 1, the regularized versions Q(s, z) = \Gamma(s,z)/\Gamma(s) and P(s,z) = \gamma(s,z)/\Gamma(s); if 2, z^{-s} \Gamma(s, z) and \gamma^*(s, z) = z^{-s} P(s, z), as for acb_hypgeom_gamma_upper and acb_hypgeom_gamma_lower.

Sets res to the incomplete beta function B(a, b; z) = \int_0^z t^{a-1} (1-t)^{b-1} \, dt with a = x, b = y, or to the regularized version I(a, b; z) = B(a, b; z)/B(a, b) if regularized is nonzero.

Set res to the generalised exponential integral E_s(z) = \int_1^\infty e^{-zt} t^{-s} \, dt with s = x and z = y, respectively the exponential integral \operatorname{Ei}(x).

Set res to the sine integral \operatorname{Si}(x), the cosine integral \operatorname{Ci}(x), the hyperbolic sine integral \operatorname{Shi}(x) or the hyperbolic cosine integral \operatorname{Chi}(x).

Sets res to the logarithmic integral \operatorname{li}(x) = \int_0^x dt / \log t, or to the offset logarithmic integral \operatorname{Li}(x) = \operatorname{li}(x) - \operatorname{li}(2) if offset is nonzero.

Sets res to the dilogarithm \operatorname{Li}_2(x).

Set res to the Bessel functions J_\nu(z), Y_\nu(z), I_\nu(z) or K_\nu(z) of order \nu = x and argument z = y; gr_bessel_j_y sets res1 to J_\nu(z) and res2 to Y_\nu(z).

Set res to the scaled Bessel functions e^{-z} I_\nu(z) and e^{z} K_\nu(z), which do not overflow for large z.

Sets res to the first len Taylor coefficients of J_\nu(z + t) at t = 0, that is, J_\nu^{(k)}(z) / k! for 0 \le k < \mathit{len} (the jet of J_\nu at z). This is a generic function, not a method: it computes J_\nu(z) and J_{\nu+1}(z) and then the higher coefficients by a three-term recurrence (https://fungrim.org/entry/9b2f38/), and uses the series expansion at z = 0 for integer \nu.

Set res to the Airy functions \operatorname{Ai}(x), \operatorname{Bi}(x) and their derivatives; gr_airy sets res1, res2, res3, res4 to \operatorname{Ai}(x), \operatorname{Ai}'(x), \operatorname{Bi}(x), \operatorname{Bi}'(x) (as acb_hypgeom_airy).

Set res to the n-th real zero a_n, b_n, a_n' or b_n' of \operatorname{Ai}, \operatorname{Bi}, \operatorname{Ai}' or \operatorname{Bi}', counted from n = 1 and ordered by decreasing value; GR_DOMAIN for n < 1.

Set res to the Coulomb wave functions F_\ell(\eta, z), G_\ell(\eta, z), H^{+}_\ell(\eta, z) and H^{-}_\ell(\eta, z) with \ell = x, \eta = y and argument z; gr_coulomb computes all four (as acb_hypgeom_coulomb).

Set res to the Chebyshev polynomials T_n(x) and U_n(x), for an integer n (the _fmpz versions, which work in any ring) or n in the ring (as hypergeometric functions in ball arithmetic).

Set res to the Jacobi polynomial P_n^{(a,b)}(z), the Gegenbauer polynomial C_n^{(m)}(z), the associated Laguerre polynomial L_n^{(m)}(z) or the Hermite polynomial H_n(z), extended to non-integer n as hypergeometric functions (as the corresponding acb_hypgeom functions).

Set res to the associated Legendre functions of the first and second kind P_n^m(z) and Q_n^m(z); type selects the branch cut convention: 0 for Ferrers' functions on (-1, 1) and 1 for the functions on \mathbb{C} \setminus (-\infty, 1] (types 2 and 3 of Mathematica), as in acb_hypgeom_legendre_p.

Sets res to the spherical harmonic Y_n^m(\theta, \phi) for integers n and m.

Sets root to the root of index k of the Legendre polynomial P_n(x), with 0 \le k < n and the roots ordered by decreasing value, and, if weight is not NULL, weight to the corresponding weight of Gauss–Legendre quadrature (as arb_hypgeom_legendre_p_ui_root). GR_DOMAIN if k \ge n.

Set res to the hypergeometric functions {}_0F_1(a; z), {}_1F_1(a; b; z) (Kummer's function M(a, b, z)) and {}_2F_1(a, b; c; z), or to their regularized versions.

Sets res to the confluent hypergeometric function of the second kind U(a, b, z) (Tricomi's function). flags is ignored.

Sets res to the generalised hypergeometric function {}_pF_q(a_1, \ldots, a_p; b_1, \ldots, b_q; z) with the parameters given by the vectors a and b, or its regularized version.

Set res to the Riemann zeta function \zeta(s); GR_DOMAIN at the pole s = 1. The method of gr_zeta_ui is implemented for real and complex balls (arb_zeta_ui); other rings return GR_UNABLE, and gr_zeta with an integer argument can be used instead.

Sets res to the Hurwitz zeta function \zeta(s, a) = \sum_{k \ge 0} (k + a)^{-s} with s = x, a = y (Zeta functions, polylogarithms and L-functions).

Sets res to the polylogarithm \operatorname{Li}_s(z) with s = x, z = y.

Sets res to the polygamma function \psi^{(s)}(z) with s = x, z = y, extended to complex s as in acb_polygamma.

Sets res to the Lerch transcendent \Phi(z, s, a) = \sum_{k \ge 0} z^k (k + a)^{-s} with z = x, s = y, a = z.

Sets res to the generalised Stieltjes constant \gamma_n(a), the coefficients of the Laurent expansion of \zeta(s, a) at s = 1.

Set res to the Dirichlet eta function \eta(s) = (1 - 2^{1-s}) \zeta(s) and the Dirichlet beta function \beta(s) = \sum_{k \ge 0} (-1)^k (2k+1)^{-s}. gr_dirichlet_beta is implemented for real and complex balls, as the Dirichlet L-function of the nontrivial character modulo 4 (acb_dirichlet_l).

Sets res to the Riemann xi function \xi(s) = \tfrac{1}{2} s (s-1) \pi^{-s/2} \Gamma(s/2) \zeta(s).

Set res to the n-th nontrivial zero \rho_n = 1/2 + i t_n of \zeta(s) in the upper half-plane, counted from n = 1 by increasing height; to the len consecutive zeros \rho_n, \rho_{n+1}, \ldots; or to the number N(t) of zeros with imaginary part in (0, t]. The ball implementations return GR_UNABLE for n < 1 and for non-real or non-finite t.

Set res to the value \chi(n) of the Dirichlet character chi of the group G, respectively the values \chi(0), \ldots, \chi(\mathit{len}-1), as complex numbers. These are not methods: they are implemented for complex balls (acb) only and return GR_UNABLE otherwise. Declared only if dirichlet.h is included first.

Sets res to the Dirichlet L-function L(s, \chi) for the character chi of the group G, in complex balls, in real balls (GR_UNABLE unless the value is real), or as a power series in gr_series rings (gr_series_dirichlet_l); GR_UNABLE in other rings.

Set res to the Hardy theta function \theta(t) and Hardy Z-function Z(t) of the character chi, defined so that Z(t) = e^{i \theta(t)} L(1/2 + it, \chi) is real for real t, with the same rings as gr_dirichlet_l.

Set res to the Jacobi theta functions \theta_j(z, \tau), with the argument scaled by \pi as in acb_modular_theta (for example \theta_3(z, \tau) = \sum_{n \in \mathbb{Z}} q^{n^2} e^{2\pi i n z}); gr_jacobi_theta computes all four.

Set res to the modular j-invariant j(\tau), the modular lambda function \lambda(\tau) or the modular discriminant \Delta(\tau).

Set res to the Dedekind eta function \eta(\tau). gr_dedekind_eta_q takes the nome q = e^{2 \pi i \tau} instead and computes \eta without the leading factor q^{1/24}, that is, q^{-1/24} \eta(\tau) = \prod_{k \ge 1} (1 - q^k) (as acb_modular_eta_sum does), which is a single-valued function of q for |q| < 1. It returns GR_DOMAIN if |q| \ge 1, and is implemented for real and complex balls.

Sets res to the value H_D(x) of the Hilbert class polynomial for the discriminant D at x. If ctx is a gr_poly ring and x its generator, the polynomial itself is returned. GR_DOMAIN if D is not a negative discriminant. The default computes H_D with acb_modular_hilbert_class_poly and evaluates it, so it works in any ring.

Set res to the Eisenstein series G_k(\tau) = \sum_{(m,n) \ne (0,0)} (m + n\tau)^{-k} or its normalisation E_k(\tau) = G_k(\tau) / (2 \zeta(k)), for even k \ge 2 (GR_DOMAIN for odd k or k = 0); gr_eisenstein_g_vec writes G_4, G_6, \ldots, G_{2\mathit{len}+2}.

Set res to the arithmetic-geometric mean M(x, y), respectively M(1, x).

Set res to the complete elliptic integrals of the first, second and third kind K(m), E(m) and \Pi(n, m).

Set res to the incomplete elliptic integrals F(\phi, m), E(\phi, m) and \Pi(n, \phi, m); if pi is nonzero, the amplitude is \pi \phi instead of \phi.

Set res to the Carlson symmetric elliptic integrals R_F(x, y, z), R_C(x, y) = R_F(x, y, y), R_D(x, y, z) = R_J(x, y, z, z), R_G(x, y, z) and R_J(x, y, z, w). flags is passed to acb_elliptic_rf and acb_elliptic_rj and should be 0.

Set res1, res2 to the lattice invariants g_2, g_3, respectively res1, res2, res3 to the roots e_1, e_2, e_3 of 4t^3 - g_2 t - g_3, of the lattice (1, \tau).

Set res to the Weierstrass elliptic function \wp(z, \tau), its derivative \wp'(z, \tau), its inverse \wp^{-1}(z, \tau) (an elliptic integral), the Weierstrass zeta function \zeta(z, \tau) or the Weierstrass sigma function \sigma(z, \tau) for the lattice (1, \tau).

Handle the trivial argument (0, or 1 for the logarithm) exactly and return GR_UNABLE otherwise.

Reduce to other functions: e^x - 1, 2^x and 10^x with gr_pow, \log(1+x), and \log(x)/\log(2) or \log(x)/\log(10) (any failure of the latter two is reported as GR_UNABLE).

Compute 1/\cos(\pi x) and 1/\sin(\pi x).

Compute the inverse function and divide by \pi.

Compute \operatorname{atan}(1/x), \operatorname{acos}(1/x), \operatorname{asin}(1/x) and the hyperbolic analogues; the inversion fails for x = 0 even where the function has a finite value.

Factorials: fmpz_fac_ui in \mathbb{Z}; a table for small n; in rings of finite characteristic, products of several consecutive integers per multiplication, and n_factorial_fast_mod2_preinv for nmod; numerically with arb_fac_ui in rings with a real precision; otherwise exactly in \mathbb{Z} and converted. gr_generic_fac uses gr_fac_ui for integer arguments and \Gamma(x + 1) otherwise.

Reciprocal factorials, computed as inverses of factorials.

Rising factorials by binary splitting of the product x (x+1) \cdots (x+n-1), with a basecase of 16 factors; falling factorials as rising factorials of x - n + 1. Non-integer y gives GR_UNABLE.

Binomial coefficients: gr_generic_bin_uiui uses fmpz_bin_uiui in \mathbb{Z}, and in other rings computes the integer exactly and converts it when n \le 100 or the ring is exact of characteristic zero, and otherwise divides a falling factorial by a factorial in the ring (falling back to the exact integer if the division fails). gr_generic_bin_ui divides the falling factorial x (x-1) \cdots (x-k+1) by k!; gr_generic_bin requires an integer y. The vec versions use recurrences between consecutive coefficients, taking care in rings of finite characteristic where divisions may not be possible.

Double factorials: (2k)!! = 2^k k! and (2k+1)!! = (2k+1)!/(2k)!!; for non-integer x the extension 2^{x/2} (\pi/2)^{(\cos(\pi x) - 1)/4} \Gamma(1 + x/2).

Harmonic numbers: exactly with fmpq_harmonic_ui and converted, or numerically in rings with a real precision.

Computes B(x, y) = \Gamma(x) \Gamma(y) / \Gamma(x + y).

Fibonacci numbers by a table for small n and otherwise the doubling formulas F_{2k-1} = F_k^2 + F_{k-1}^2, F_{2k+1} = 4F_k^2 - F_{k-1}^2 + 2(-1)^k along the binary expansion of n. gr_generic_fib2_fmpz sets v to F_n and u to F_{n-1}. The vec version uses the recurrence.

Bell numbers: exactly in \mathbb{Z} with the functions of arith, numerically in rings with a real precision, directly modulo n for nmod (arith_bell_number_nmod and arith_bell_number_nmod_vec), and otherwise exactly in \mathbb{Z} and converted.

Partition numbers: partitions_fmpz_ui (the Hardy–Ramanujan–Rademacher formula [Joh2012]) in \mathbb{Z}, numerically in rings with a real precision, and otherwise exactly and converted. The vec version uses arith_number_of_partitions_vec in \mathbb{Z} and arith_number_of_partitions_nmod_vec for nmod (power series inversion of \prod (1 - x^k)), numerical values in rings with a real precision, and otherwise exact values converted.

Chebyshev polynomials T_n(x) and U_n(x) for n \ge 0 by the doubling formulas T_{2k} = 2T_k^2 - 1 and T_{2k+1} = 2 T_k T_{k+1} - x (and analogues for U) along the binary expansion of n, using O(\log n) multiplications. The 2 versions set a to T_n(x) and b to T_{n-1}(x) (respectively U). Negative n gives GR_UNABLE.

Computes e^{x^2} \operatorname{erfc}(x) directly from gr_exp and gr_erfc, which is not numerically stable for large x; failures are reported as GR_UNABLE.

Computes H_D with acb_modular_hilbert_class_poly and evaluates it at x (or returns it in a polynomial ring); GR_DOMAIN if D is not a negative discriminant.