Hypergeometric Function of a Matrix Argument

Back

Current version: 1.5, posted February 12, 2018.


What's new in 1.5:

  1. Introducing new functions mhgA1A and mhgA1B for computing the hypergeometric function faster when alpha=1. See below.

What was new in 1.4:
  1. The only changes pertain to mhg.c.
  2. Introduced a way to restrict the summation over partitions kappa \subset \lambda.
  3. Automatically restricting the summation over partitions in <=min(rank X, rank Y) parts.
  4. Automatically restricting the summation to partitions of only one part if one of the p_i's equals 1/alpha = beta/2.

What was new in 1.3: Improved algorithms for mhg and mhgi which should be faster than the previous versions. logmhg remains unchanged.

Previous versions: 1.0, 1.1, 1.2, 1.3. 1.4.

Installation instructions:

Download and unzip the linked file. Recompile the C files (by typing, e.g., "mex mhg.c" at the MATLAB prompt).

How to cite:

Plamen Koev and Alan Edelman, The efficient evaluation of the hypergeometric function of a matrix argument, Math. Comp. 75 (2006), 833-846.

General comments:

  • How do these algorithms work? See our paper.
  • Only REAL arguments can be passed. If you need to use COMPLEX or SYMBOLIC arguments, please contact me.

Function description:

mhg

Syntax: [s,c]=mhg([M K lambda],alpha,a,b,x,y)
Description: Computes the truncated Hypergeometric function of one or two matrix arguments
pFq(alpha)( a1,..., ap; b1,..., bq; X, Y) as a series of Jack functions, truncated for partitions of size not exceeding M.
Arguments:
  • alpha is positive real
    (typically alpha=2 in settings involving REAL random matrices, and alpha=1 in settings involving COMPLEX random matrices);
  • a and b are real arrays;
  • x and y are real arrays containing the eigenvalues of the matrix arguments X and Y, respectively;
  • The argument y may be omitted.
  • The argument K may be omitted but if specified, the summation is over partitions kappa such that kappa[1]<=K.
  • The argument lambda may be omitted, but if specified, the summation is over partitions kappa such that kappa[i]<=lambda[i] for i=1,2,...
Output:
  • s is the value of the truncated hypergeometric function
  • c is a vector of size M+1 with the marginal sums for partitions of size 0,1,...,M (thus s=sum(c)).
Comments: Larger values of M will yield more accurate results. There are no rules on selecting the optimal M. Start with (say) M=10 and experiment until you obtain the best value of M for your application. The values of the output vector c may give you some idea about the convergence.
Example 1: mhg(20,2,[0.1,0.2],[0.3,0.4],[0.5 0.6 0.7]) returns 3.1349, which is a good approximation to
2F2(2)(0.1,0.2; 0.3,0.4; diag(0.5,0.6,0.7)).
Example 2: mhg(20,1,[ ],[0.1],[0.2 0.3 0.4],[0.5 0.6 0.7]) returns 6.6265, which is a good approximation to
0F1(1)(0.1; diag(0.2,0.3,0.4),diag(0.5,0.6,0.7)).
Example 3: mhg([20 4],1,[0.8],[0.1],[0.2 0.3 0.4]) returns 13.4183, which is an approximation to
1F1(1)(0.8;0.1; diag(0.2,0.3,0.4)) summed over partitions whose size does not exceed 20 and all of whose parts do not exceed 4.
Example 4: mhg([10 4 4 3 1],1,[0.8],[0.1],[0.2 0.3 0.4]) returns 13.4182, which is an approximation to
1F1(1)(0.8;0.1; diag(0.2,0.3,0.4)) summed over partitions kappa whose size does not exceed 20 AND all of whose parts do not exceed 4 AND kappa[1]<=4, kappa[2]<=3, kappa[3]<=1.

mhgi

Syntax: [s,c]=mhgi(M,alpha,a,b,n,x)
Description: Same as mhg when X=xIn is a multiple of the identity (but using a much more efficient algorithm available for this special case).
Arguments:
  • alpha, a, and b are as in mhg
  • M can now be a vector with 1 or 2 elements. If M is a vector with one element, then it serves the same purpose as in mhg above. The second, optional element in M, call it M(2), is such that the summation is only over partitions whose parts do not exceed M(2)
  • n is the size of the matrix argument
  • x is a real number or a vector of real numbers
Output:
  • s is the value of the truncated hypergeometric function evaluated at each element of the vector x
  • Since s is a polynomial in x of degree M, the output vector c contains the coefficients of that polynomial. This way s=c(1)+x*c(2)+x^2*c(3)+...+x^M*c(M+1), which is meant componentwise when x is a vector. Equivalently, in MATLAB notation, s=polyval(c(end:-1:1),x).
Comments: The output vector c is slightly different in mhg and mhgi.
Example: mhgi(20,1,[ ],[0.1],3,[0.5 0.6]) returns the vector [11.9545, 9.3686], which is a good approximation to 0F1(1)(0.1; x I3) for x=0.5 and 0.6, respectively.

logmhg

Syntax: g=logmhg(M,alpha,a,b,x,y)
Description: Same as mhg, but computes its natural logarithm. Useful in cases when mhg overflows and has only one output argument.

mhgA1A

Syntax: [s,c]=mhgA1A(M,a,b,x[,y])
Description: Same as mhg when alpha=1, but computed much more efficiently using the FIRST algorithm described in "On Computing Schur functions and Series Thereof" by Chan, Drensky, Edelman, Kan, and Koev. Download Cy Chan's package and compile using compileScript.

mhgA1B

Syntax: [s,c]=mhgA1B(M,a,b,x[,y])
Description: Same as mhg when alpha=1, but computed much more efficiently using the SECOND algorithm described in "On Computing Schur functions and Series Thereof" by Chan, Drensky, Edelman, Kan, and Koev.
Plamen Koev
Department of Mathematics, Massachusetts Institute of Technology
"firstname" dot "lastname" AT sjsu.edu