A hypergeometric template is a pair of multisets (i.e., sets with possibly repeated elements) of rational numbers (α₁,...,α_d) and (β₁,...,β_d) having the same number of elements, and we set A(x) = ∏_{1 ≤ j ≤ d}(x-e^{2π iα_j}), B(x) = ∏_{1 ≤ k ≤ d}(x-e^{2π iβ_k}) . We make the following assumptions:

* α_j-β_k ∉ ℤ for all j and k, or equivalently gcd(A,B) = 1.

* α_j ∉ ℤ for all j, or equivalently A(1) ! = 0.

* our template is defined over ℚ, in other words A,B ∈ ℤ[x], or equivalently if some a/D with gcd(a,D) = 1 occurs in the α_j or β_k, then all the b/D modulo 1 with gcd(b,D) = 1 also occur.

The last assumption allows to abbreviate [a₁/D,...,a_φ(D)/D] (where the a_i range in (ℤ/Dℤ)^*) to [D]. We thus have two possible ways of giving a hypergeometric template: either by the two vectors [α₁,...,α_d] and [β₁,...,β_d], or by their denominators [D₁,...,D_m] and [E₁,...,E_n] , which are called the cyclotomic parameters; note that ∑_jφ(D_j) = ∑_kφ(E_k) = d. A third way is to give the gamma vector (γ_n) defined by A(X)/B(X) = ∏_n(Xⁿ-1)^γ_n, which satisfies ∑_n nγ_n = 0. To any such data we associate a hypergeometric template using the function hgminit; then the α_j and β_k are obtained using hgmalpha, cyclotomic parameters using hgmcyclo and the gamma vectors using hgmgamma.

To such a hypergeometric template is associated a number of additional parameters, for which we do not give the definition but refer to the survey Hypergeometric Motives by Roberts and Villegas, https://arxiv.org/abs/2109.00027: the degree d, the weight w, a Hodge polynomial P, a Tate twist T, and a normalizing M-factor M = ∏_n n^nγ_n. The hgmparams function returns [d,w,[P,T],M] . Example with cyclotomic parameters [5],[1,1,1,1]:

  ? H = hgminit([5]); \\ [1,1,1,1] can be omitted
  ? hgmparams(H)
  %2 = [4, 3, [x^3+x^2+x+1,0], 3125]
  ? hgmalpha(H)
  %3 = [[1/5, 2/5, 3/5, 4/5], [0, 0, 0, 0]]
  ? hgmcyclo(H)
  %4 = [Vecsmall([5]), Vecsmall([1, 1, 1, 1])]
  ? hgmgamma(H)
  %5 = Vecsmall([-5,0,0,0,1]) \\ A/B = (x^5-1) / (x-1)^5

A hypergeometric motive (HGM for short) is a pair (H,t), where H is a hypergeometric template and t ∈ ℚ^*. To such a motive and a finite field 𝔽_q one can associate via an explicit but complicated formula an integer N(H,t; q), see Beukers, Cohen and Mellit, Finite hypergeometric functions Pure and Applied Math Quarterly 11 (2015), pp 559 - 589, https://arxiv.org/abs/1505.02900.

Warning. Depending on the authors, t may have to be replaced with 1/t. The Pari/GP convention is the same as the one in Magma, but is the inverse of the one in the last reference.

This formula does not make sense and is not valid for bad primes p: a wild prime is a prime which divides a denominator of the α_j or β_i. If a prime p is not wild, it can be good if v_p(t) = v_p(t-1) = 0, or tame otherwise. The local Euler factor P_p at a good prime p is then given by the usual formula -log P_p(T) = ∑_{f ≥ 1} (N(H,t; p^f) T^f)/(f) , and in the case of HGM's P_p is always a polynomial (note that the Euler factor used in the global L-function is 1/P_p(p^-s)). At a tame prime p it is necessary to modify the above formula, and usually (but not always) the degree of the local Euler factor decreases. Wild primes are currently not implemented by a formula but can be guessed via the global functional equation (see the next section). Continuing the previous example, we find

  ? hgmeulerfactor(H, -1, 3) \\ good prime
  %4 = 729*x^4 + 135*x^3 + 45*x^2 + 5*x + 1
  ? hgmeulerfactor(H, -1, 2) \\ tame prime
  %5 = 16*x^3 + 6*x^2 + x + 1
  ? hgmeulerfactor(H, -1, 5) \\ wild primes not implemented
  %6 = 0

To obtain the Euler factor at wild primes, use lfuneuler once the global L-function is computed.

A theorem of Katz tells us that if one suitably defines P_p(T) for all primes p including the wild ones, then the L-function defined by L(H,s) = ∏_p P_p(p^-s)^-1 is motivic, with analytic continuation and functional equation, as used in the L-function package of Pari/GP. The command L = lfunhgm(H,t) creates such an L-function. In particular it must guess the local Euler factors at wild primes, which can be very expensive when the conductor lfunparams(L)[1] is large.

In our example, L = lfunhgm(H,1/64) finishes in about 20 seconds (the conductor is only 525000); this L-function can then be used with all the functions of the lfun package. For instance we can now obtain the global conductor and check the Euler factors at all bad primes:

  ? [N] = lfunparams(L); N \\ the conductor
  %7 = 525000
  ? factor(N)
  %8 =
  [2 3]
  
  [3 1]
  
  [5 5]
  
  [7 1]
  
  ? lfuneuler(L,2)
  %9 = 1/(-x + 1)
  ? lfuneuler(L,3)
  %10 = 1/(81*x^3 + 6*x^2 - 4*x + 1)
  ? lfuneuler(L,5)
  %11 = 1
  ? lfuneuler(L,7)
  %12 = 1/(2401*x^3 + 301*x^2 + x + 1)

Two additional functions related to the global L-function are available which do not require its full initialization: hgmcoefs(H,t,n) computes the first n coefficients of the L-function by setting all wild Euler factors to 1; this will be identical to lfunan(L,n) when this is indeed the case (as in the above example: only 5 is wild), otherwise all coefficients divisible by a wild prime will be wrong.

The second is the function hgmcoef(H,t,n) which only computes the nth coefficient of the global L-function. It gives an error if n is divisible by a wild prime. Compare hgmcoefs(H,1/64,7^6)[7^6] which requires more than 1 minute (it computes more than 100000 coefficients), with hgmcoef(H,1/64,7^6) which outputs -25290600 instantaneously.

Returns the alpha and beta parameters of the hypergeometric motive template H.

  ? H = hgminit([5]); \\ template given by cyclotomic parameters
  ? hgmalpha(H)
  %2 = [[1/5, 2/5, 3/5, 4/5], [0, 0, 0, 0]]

The library syntax is GEN hgmalpha(GEN H).

Outputs [L(0),...,L(n-1)] where L(w) is the list of cyclotomic parameters of all possible hypergeometric motive templates of degree n and weight w.

The library syntax is GEN hgmbydegree(long n).

(H,t) being a hypergeometric motive, returns the n-th coefficient of its L-function. This is not implemented for wild primes p and will raise an exception if such a p divides n.

The library syntax is GEN hgmcoef(GEN H, GEN t, GEN n).

(H,t) being a hypergeometric motive, returns the first n coefficients of its L-function, where Euler factors at wild primes are set to 1. The argument t may be replaced by [t,bad] where bad is a vector of pairs [p,L_p], p being a prime and L_p being the corresponding local Euler factor, overriding the default.

If you hope that the wild Euler factors can be computed not too slowly from the functional equation, you can also set L = lfunhgm(H,t), and then lfunan(L,n), and then the Euler factors at wild primes should be correct.

The library syntax is GEN hgmcoefs(GEN H, GEN t, long n).

Returns the cyclotomic parameters (D,E) of the hypergeometric motive template H.

  \\ template given by alpha (implied beta is [0,0,0,0])
  ? H = hgminit([1/5, 2/5, 3/5, 4/5]);
  ? hgmcyclo(H)
  %3 = [Vecsmall([5]), Vecsmall([1, 1, 1, 1])]
  ? apply(Vec, %) \\ for readability
  %4 = [[5], [1, 1, 1, 1]]

The library syntax is GEN hgmcyclo(GEN H).

(H,t) being a hypergeometric motive, returns the inverse of its Euler factor at the prime p and the exponent e of the conductor at p. This is not implemented when p is a wild prime: the function returns 0 and sets e to -1. Caveat: contrary to lfuneuler, this function returns the inverse of the Euler factor, given by a polynomial P_p such that the Euler factor is 1 / P_p(p^-s).

  ? H = hgminit([5]); \\ cyclotomic parameters [5] and [1,1,1,1]
  ? hgmeulerfactor(H, 1/2, 3)
  %2 = 729*x^4 + 135*x^3 + 45*x^2 + 5*x + 1
  ? hgmeulerfactor(H, 1/2, 3, &e)
  %3 = 729*x^4 + 135*x^3 + 45*x^2 + 5*x + 1
  ? e
  %4 = 0
  ? hgmeulerfactor(H, 1/2, 2, &e)
  %5 = -x + 1
  ? e
  %6 = 3
  ? hgmeulerfactor(H, 1/2, 5)
  %7 = 0  \\ 5 is wild

If the conductor is small, the wild Euler factors can be computed from the functional equation: set L = lfunhgm(H,t) (the complexity should be roughly proportional to the conductor) then the lfuneuler function should give you the correct Euler factors at all primes:

  ? L = lfunhgm(H, 1/2);
  time = 790 ms.  \\ fast in this case, only 5 is wild
  ? lfunparams(L)   \\ ... and the conductor 5000 is small
  %8 = [5000, 4, [-1, 0, 0, 1]]
  ? lfuneuler(L, 5)
  %9 = 1 \\ trivial Euler factor
  
  ? L = lfunhgm(H, 1/64); lfunparams(L)
  time = 20,122 ms. \\ slower: the conductor is larger
  %10 = [525000, 4, [-1, 0, 0, 1]]
  
  ? L = lfunhgm(H, 1/128); lfunparams(L)
  time = 2min, 16,205 ms. \\ even slower, etc.
  %11 = [3175000, 4, [-1, 0, 0, 1]]

The library syntax is GEN hgmeulerfactor(GEN H, GEN t, long p, GEN *e = NULL).

Returns the gamma vector of the hypergeometric motive template H.

  ? H = hgminit([5]);
  ? hgmgamma(H)
  %2 = Vecsmall([-5, 0, 0, 0, 1])

The library syntax is GEN hgmgamma(GEN H).

Create the template for the hypergeometric motive with parameters a and possibly b. The format of the parameters may be

* alpha: lists of rational numbers a = (α_j) and b = (β_k) of the same length (and defined over ℚ); if b is omitted, we take it to be (0,...,0).

* cyclo: lists a = D and b = E of positive integers corresponding to the denominators of the (α_i) and (β_i); if b is omitted we take it to be (1,...,1). This is the simplest and most compact input format.

* gamma: list of γ_n such that the ∏_j(x-exp(2π iα_j)) / ∏_k(x-exp(2π iβ_k)) = ∏_n(xⁿ-1)^γ_n.

The hypergeometric motive itself is given by a pair (H,t), where H is a template as above and t ∈ ℚ^*. Note that the motives given by (α, β; t) and (β,α; 1/t) are identical.

  ? H = hgminit([5]); \\ template given by cyclotomic parameters 5 and 1,1,1,1
  ? L = lfunhgm(H, 1); \\ global L-function attached to motive (H,1)
  ? lfunparams(L)
  %3 = [25, 4, [0, 1]]
  
  ? hgmalpha(H)
  %4 = [[1/5, 2/5, 3/5, 4/5], [0, 0, 0, 0]]
  ? hgmgamma(H)
  %5 = Vecsmall([-5, 0, 0, 0, 1])

The library syntax is GEN hgminit(GEN a, GEN b = NULL).

Is the hypergeometric motive template H symmetrical at t = 1? This means that the α_j and β_k defining the template are obtained from one another by adding 1/2 (modulo 1), see hgmtwist.

  ? H = hgminit([2,2]);
  ? hgmalpha(H)
  %2 = [[1/2, 1/2], [0, 0]]
  ? hgmissymmetrical(H)
  %3 = 1 \\ this template is symmetrical
  
  ? H = hgminit([5]);
  ? hgmalpha(H)
  %5 = [[1/5, 2/5, 3/5, 4/5], [0, 0, 0, 0]]
  ? hgmissymmetrical(H)
  %6 = 1 \\ this one is not

The library syntax is long hgmissymmetrical(GEN H).

H being a hypergeometric motive template, returns [d,w,[P,T], M], where d is the degree, w the weight, P the Hodge polynomial, and T the Tate twist number (so that the Hodge function itself is P/x^T); finally the normalizing factor M is the so-called M-value, M = ∏_n n^nγ_n.

The library syntax is GEN hgmparams(GEN H).

Twist by 1/2 of alpha and beta of the hypergeometric motive template H.

  ? H = hgminit([5]);
  ? hgmalpha(H)
  %2 = [[1/5, 2/5, 3/5, 4/5], [0, 0, 0, 0]]
  ? H2 = hgmtwist(H);
  ? hgmalpha(H2)
  %4 = [[1/10, 3/10, 7/10, 9/10], [1/2, 1/2, 1/2, 1/2]]

The template is symmetrical (hgmissymmetrical) if it is equal to its twist.

The library syntax is GEN hgmtwist(GEN H).

(H,t) being a hypergeometric motive, returns the corresponding lfuncreate data for use with the L-function package. This function needs to guess local conductors and euler factors at wild primes and will be very costly if there are many such primes: the complexity is roughly proportional to the conductor. The optional parameter hint allows to speed up the function by making various assumptions:

* hint = lim a t_INT: assume that Euler factors at wild primes have degree less than lim, which may speed it up a little.

* hint = [N]: guess that the conductor is N.

* hint = [N, lim]: initial guess N for the conductor and limit degrees to lim.

If your guess for lim is wrong, the function will enter an infinite loop. If your guess for an initial N is wrong, the function silently restarts (it will not enter an infinite loop unless a simultaneous failed guess for lim is made).

  ? H = hgminit([5]);
  ? L = lfunhgm(H, 1/64);
  time = 23,113 ms.
  ? L=lfunhgm(H,1/64,0); \\ assume Euler factors at wild primes are trivial
  time = 19,721 ms. \\ a little faster
  ? L=lfunhgm(H,1/64,[525000]); \\ initial guess N = 525000
  time = 15,486 ms. \\ a little faster
  ? L=lfunhgm(H,1/64,[525000, 0]);
  time = 15,293 ms. \\ marginally faster with both assumptions

The library syntax is GEN lfunhgm(GEN H, GEN t, GEN hint = NULL, long bitprec).