# pyhypergeomatrix
<!-- badges: start -->
[](http://pyhypergeomatrix.readthedocs.io)
<!-- badges: end -->
*Hypergeometric functions of a matrix argument.*
___
## Evaluation of the hypergeometric function of a matrix argument (Koev & Edelman's algorithm)
Let $(a\_1, \ldots, a\_p)$ and $(b\_1, \ldots, b\_q)$ be two vectors of real or
complex numbers, possibly empty, $\alpha > 0$ and $X$ a real symmetric or a
complex Hermitian matrix.
The corresponding *hypergeometric function of a matrix argument* is defined by
$${}\_pF\_q^{(\alpha)} \left(\begin{matrix} a\_1, \ldots, a\_p \\\\ b\_1, \ldots, b\_q\end{matrix}; X\right) = \sum\_{k=0}^{\infty}\sum\_{\kappa \vdash k} \frac{{(a\_1)}\_{\kappa}^{(\alpha)} \cdots {(a\_p)}\_{\kappa}^{(\alpha)}} {{(b\_1)}\_{\kappa}^{(\alpha)} \cdots {(b\_q)}\_{\kappa}^{(\alpha)}} \frac{C\_{\kappa}^{(\alpha)}(X)}{k!}.$$
The inner sum is over the integer partitions $\kappa$ of $k$ (which we also
denote by $|\kappa| = k$). The symbol ${(\cdot)}\_{\kappa}^{(\alpha)}$ is the
*generalized Pochhammer symbol*, defined by
$${(c)}^{(\alpha)}\_{\kappa} = \prod\_{i=1}^{\ell}\prod\_{j=1}^{\kappa\_i} \left(c - \frac{i-1}{\alpha} + j-1\right)$$
when $\kappa = (\kappa\_1, \ldots, \kappa\_\ell)$.
Finally, $C\_{\kappa}^{(\alpha)}$ is a *Jack function*.
Given an integer partition $\kappa$ and $\alpha > 0$, and a
real symmetric or complex Hermitian matrix $X$ of order $n$,
the Jack function
$$C\_{\kappa}^{(\alpha)}(X) = C\_{\kappa}^{(\alpha)}(x\_1, \ldots, x\_n)$$
is a symmetric homogeneous polynomial of degree $|\kappa|$ in the
eigen values $x\_1$, $\ldots$, $x\_n$ of $X$.
The series defining the hypergeometric function does not always converge.
See the references for a discussion about the convergence.
The inner sum in the definition of the hypergeometric function is over
all partitions $\kappa \vdash k$ but actually
$C\_{\kappa}^{(\alpha)}(X) = 0$ when $\ell(\kappa)$, the number of non-zero
entries of $\kappa$, is strictly greater than $n$.
For $\alpha=1$, $C\_{\kappa}^{(\alpha)}$ is a *Schur polynomial* and it is
a *zonal polynomial* for $\alpha = 2$.
In random matrix theory, the hypergeometric function appears for $\alpha=2$
and $\alpha$ is omitted from the notation, implicitely assumed to be $2$.
Koev and Edelman (2006) provided an efficient algorithm for the evaluation
of the truncated series
$$\sideset{\_p^m}{\_q^{(\alpha)}}F \left(\begin{matrix} a\_1, \ldots, a\_p \\\\ b\_1, \ldots, b\_q\end{matrix}; X\right) = \sum\_{k=0}^{m}\sum\_{\kappa \vdash k} \frac{{(a\_1)}\_{\kappa}^{(\alpha)} \cdots {(a\_p)}\_{\kappa}^{(\alpha)}} {{(b\_1)}\_{\kappa}^{(\alpha)} \cdots {(b\_q)}\_{\kappa}^{(\alpha)}}
\frac{C\_{\kappa}^{(\alpha)}(X)}{k!}.$$
Hereafter, $m$ is called the *truncation weight of the summation*
(because $|\kappa|$ is called the weight of $\kappa$), the vector
$(a\_1, \ldots, a\_p)$ is called the vector of *upper parameters* while
the vector $(b\_1, \ldots, b\_q)$ is called the vector of *lower parameters*.
The user has to supply the vector $(x\_1, \ldots, x\_n)$ of the eigenvalues
of $X$.
For example, to compute
$$\sideset{\_2^{15}}{\_3^{(2)}}F \left(\begin{matrix} 3, 4 \\\\ 5, 6, 7\end{matrix}; 0.1, 0.4\right)$$
you have to enter
```haskell
>>> from pyhypergeomatrix.hypergeomat import hypergeomPQ
>>> hypergeomPQ(15, [3, 4], [5, 6, 7], [0.1, 0.4], 2)
```
We said that the hypergeometric function is defined for a real symmetric
matrix or a complex Hermitian matrix $X$. Thus the eigenvalues of $X$
are real. However we do not impose this restriction in `pyhypergeomatrix`.
The user can enter any list of real or complex numbers for the eigenvalues.
### Univariate case
For $n = 1$, the hypergeometric function of a matrix argument is known as the
[generalized hypergeometric function](https://mathworld.wolfram.com/HypergeometricFunction.html).
It does not depend on $\alpha$. The case of $\sideset{\_{2\thinspace}^{}}{\_1^{}}F$ is the most known,
this is the Gauss hypergeometric function. Let's check a value. It is known that
$$\sideset{\_{2\thinspace}^{}}{\_1^{}}F \left(\begin{matrix} 1/4, 1/2 \\\\ 3/4\end{matrix}; 80/81\right) = 1.8.$$
Since $80/81$ is close to $1$, the convergence is slow. We compute the truncated series below
for $m = 300$.
```python
>>> from pyhypergeomatrix.hypergeomat import hypergeomPQ
>>> hypergeomPQ(300, [1/4, 1/2], [3/4], [80/81])
1.79900265281923
```
## References
- Plamen Koev and Alan Edelman.
*The efficient evaluation of the hypergeometric function of a matrix argument*.
Mathematics of computation, vol. 75, n. 254, 833-846, 2006.
- Robb Muirhead.
*Aspects of multivariate statistical theory*.
Wiley series in probability and mathematical statistics.
Probability and mathematical statistics.
John Wiley & Sons, New York, 1982.
- A. K. Gupta and D. K. Nagar.
*Matrix variate distributions*.
Chapman and Hall, 1999.
Raw data
{
"_id": null,
"home_page": "https://github.com/stla/pyhypergeomatrix",
"name": "pyhypergeomatrix",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "mathematics,special functions",
"author": "St\u00e9phane Laurent",
"author_email": "laurent_step@outlook.fr",
"download_url": "https://files.pythonhosted.org/packages/78/69/f0878d287f5c722c73373059a8c98a637c0f056aced743b559d6422a71d3/pyhypergeomatrix-0.1.0.tar.gz",
"platform": null,
"description": "# pyhypergeomatrix\n\n<!-- badges: start -->\n[](http://pyhypergeomatrix.readthedocs.io)\n<!-- badges: end -->\n\n*Hypergeometric functions of a matrix argument.*\n\n___\n\n## Evaluation of the hypergeometric function of a matrix argument (Koev & Edelman's algorithm)\n\nLet $(a\\_1, \\ldots, a\\_p)$ and $(b\\_1, \\ldots, b\\_q)$ be two vectors of real or \ncomplex numbers, possibly empty, $\\alpha > 0$ and $X$ a real symmetric or a \ncomplex Hermitian matrix. \nThe corresponding *hypergeometric function of a matrix argument* is defined by \n\n$${}\\_pF\\_q^{(\\alpha)} \\left(\\begin{matrix} a\\_1, \\ldots, a\\_p \\\\\\\\ b\\_1, \\ldots, b\\_q\\end{matrix}; X\\right) = \\sum\\_{k=0}^{\\infty}\\sum\\_{\\kappa \\vdash k} \\frac{{(a\\_1)}\\_{\\kappa}^{(\\alpha)} \\cdots {(a\\_p)}\\_{\\kappa}^{(\\alpha)}} {{(b\\_1)}\\_{\\kappa}^{(\\alpha)} \\cdots {(b\\_q)}\\_{\\kappa}^{(\\alpha)}} \\frac{C\\_{\\kappa}^{(\\alpha)}(X)}{k!}.$$\n\nThe inner sum is over the integer partitions $\\kappa$ of $k$ (which we also \ndenote by $|\\kappa| = k$). The symbol ${(\\cdot)}\\_{\\kappa}^{(\\alpha)}$ is the \n*generalized Pochhammer symbol*, defined by\n\n$${(c)}^{(\\alpha)}\\_{\\kappa} = \\prod\\_{i=1}^{\\ell}\\prod\\_{j=1}^{\\kappa\\_i} \\left(c - \\frac{i-1}{\\alpha} + j-1\\right)$$\n\nwhen $\\kappa = (\\kappa\\_1, \\ldots, \\kappa\\_\\ell)$. \nFinally, $C\\_{\\kappa}^{(\\alpha)}$ is a *Jack function*. \nGiven an integer partition $\\kappa$ and $\\alpha > 0$, and a \nreal symmetric or complex Hermitian matrix $X$ of order $n$, \nthe Jack function \n\n$$C\\_{\\kappa}^{(\\alpha)}(X) = C\\_{\\kappa}^{(\\alpha)}(x\\_1, \\ldots, x\\_n)$$\n\nis a symmetric homogeneous polynomial of degree $|\\kappa|$ in the \neigen values $x\\_1$, $\\ldots$, $x\\_n$ of $X$. \n\nThe series defining the hypergeometric function does not always converge. \nSee the references for a discussion about the convergence. \n\nThe inner sum in the definition of the hypergeometric function is over \nall partitions $\\kappa \\vdash k$ but actually \n$C\\_{\\kappa}^{(\\alpha)}(X) = 0$ when $\\ell(\\kappa)$, the number of non-zero \nentries of $\\kappa$, is strictly greater than $n$.\n\nFor $\\alpha=1$, $C\\_{\\kappa}^{(\\alpha)}$ is a *Schur polynomial* and it is \na *zonal polynomial* for $\\alpha = 2$. \nIn random matrix theory, the hypergeometric function appears for $\\alpha=2$ \nand $\\alpha$ is omitted from the notation, implicitely assumed to be $2$. \n\nKoev and Edelman (2006) provided an efficient algorithm for the evaluation \nof the truncated series \n\n$$\\sideset{\\_p^m}{\\_q^{(\\alpha)}}F \\left(\\begin{matrix} a\\_1, \\ldots, a\\_p \\\\\\\\ b\\_1, \\ldots, b\\_q\\end{matrix}; X\\right) = \\sum\\_{k=0}^{m}\\sum\\_{\\kappa \\vdash k} \\frac{{(a\\_1)}\\_{\\kappa}^{(\\alpha)} \\cdots {(a\\_p)}\\_{\\kappa}^{(\\alpha)}} {{(b\\_1)}\\_{\\kappa}^{(\\alpha)} \\cdots {(b\\_q)}\\_{\\kappa}^{(\\alpha)}} \n\\frac{C\\_{\\kappa}^{(\\alpha)}(X)}{k!}.$$\n\nHereafter, $m$ is called the *truncation weight of the summation* \n(because $|\\kappa|$ is called the weight of $\\kappa$), the vector \n$(a\\_1, \\ldots, a\\_p)$ is called the vector of *upper parameters* while \nthe vector $(b\\_1, \\ldots, b\\_q)$ is called the vector of *lower parameters*. \nThe user has to supply the vector $(x\\_1, \\ldots, x\\_n)$ of the eigenvalues \nof $X$. \n\nFor example, to compute\n\n$$\\sideset{\\_2^{15}}{\\_3^{(2)}}F \\left(\\begin{matrix} 3, 4 \\\\\\\\ 5, 6, 7\\end{matrix}; 0.1, 0.4\\right)$$\n\nyou have to enter \n\n```haskell\n>>> from pyhypergeomatrix.hypergeomat import hypergeomPQ\n>>> hypergeomPQ(15, [3, 4], [5, 6, 7], [0.1, 0.4], 2)\n```\n\nWe said that the hypergeometric function is defined for a real symmetric \nmatrix or a complex Hermitian matrix $X$. Thus the eigenvalues of $X$ \nare real. However we do not impose this restriction in `pyhypergeomatrix`. \nThe user can enter any list of real or complex numbers for the eigenvalues. \n\n\n### Univariate case\n\nFor $n = 1$, the hypergeometric function of a matrix argument is known as the \n[generalized hypergeometric function](https://mathworld.wolfram.com/HypergeometricFunction.html). \nIt does not depend on $\\alpha$. The case of $\\sideset{\\_{2\\thinspace}^{}}{\\_1^{}}F$ is the most known, \nthis is the Gauss hypergeometric function. Let's check a value. It is known that\n\n$$\\sideset{\\_{2\\thinspace}^{}}{\\_1^{}}F \\left(\\begin{matrix} 1/4, 1/2 \\\\\\\\ 3/4\\end{matrix}; 80/81\\right) = 1.8.$$\n\nSince $80/81$ is close to $1$, the convergence is slow. We compute the truncated series below \nfor $m = 300$.\n\n```python\n>>> from pyhypergeomatrix.hypergeomat import hypergeomPQ\n>>> hypergeomPQ(300, [1/4, 1/2], [3/4], [80/81])\n1.79900265281923\n```\n\n\n## References\n\n- Plamen Koev and Alan Edelman. \n*The efficient evaluation of the hypergeometric function of a matrix argument*.\nMathematics of computation, vol. 75, n. 254, 833-846, 2006.\n\n- Robb Muirhead. \n*Aspects of multivariate statistical theory*. \nWiley series in probability and mathematical statistics. \nProbability and mathematical statistics. \nJohn Wiley & Sons, New York, 1982.\n\n- A. K. Gupta and D. K. Nagar. \n*Matrix variate distributions*. \nChapman and Hall, 1999.",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Hypergeometric functions of a matrix argument.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://pyhypergeomatrix.readthedocs.io/en/latest/",
"Homepage": "https://github.com/stla/pyhypergeomatrix"
},
"split_keywords": [
"mathematics",
"special functions"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dc225ba9c2275195fa6647da5a6c67082bf72563878d0d3af91daf62ffd0a37c",
"md5": "562a0e7a2aee2d477f7a3f1f2ac13e52",
"sha256": "14899bbaeee021f85bac72b3c2ff91b039e08235b1389a199643b3591de94d9a"
},
"downloads": -1,
"filename": "pyhypergeomatrix-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "562a0e7a2aee2d477f7a3f1f2ac13e52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 17914,
"upload_time": "2023-12-07T18:21:00",
"upload_time_iso_8601": "2023-12-07T18:21:00.030745Z",
"url": "https://files.pythonhosted.org/packages/dc/22/5ba9c2275195fa6647da5a6c67082bf72563878d0d3af91daf62ffd0a37c/pyhypergeomatrix-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7869f0878d287f5c722c73373059a8c98a637c0f056aced743b559d6422a71d3",
"md5": "3fda10b463a76588cd3ce05257cef59d",
"sha256": "ef5e8e102fbced76101d46273f3bf8cfc3797f9f1ad8e4fc049cc725bf4cd8c0"
},
"downloads": -1,
"filename": "pyhypergeomatrix-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3fda10b463a76588cd3ce05257cef59d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 17747,
"upload_time": "2023-12-07T18:21:02",
"upload_time_iso_8601": "2023-12-07T18:21:02.019464Z",
"url": "https://files.pythonhosted.org/packages/78/69/f0878d287f5c722c73373059a8c98a637c0f056aced743b559d6422a71d3/pyhypergeomatrix-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-07 18:21:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stla",
"github_project": "pyhypergeomatrix",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyhypergeomatrix"
}
JSON
