From de3ca91ecf295491a1debf30a8386df34a6b876f Mon Sep 17 00:00:00 2001
From: Andrew Johnson <andrew.johnson@arjohnsonau.com>
Date: Sat, 22 Mar 2025 20:21:41 +0800
Subject: [PATCH 1/3] Add docs for hypergeometric functions
---
.../real-valued_basic_functions.qmd | 62 +++++++++++++++++++
1 file changed, 62 insertions(+)
diff --git a/src/functions-reference/real-valued_basic_functions.qmd b/src/functions-reference/real-valued_basic_functions.qmd
index e0e2c6648..ab4950b76 100644
--- a/src/functions-reference/real-valued_basic_functions.qmd
+++ b/src/functions-reference/real-valued_basic_functions.qmd
@@ -1698,3 +1698,65 @@ Implementation of the $W_0$ branch of the Lambert W function, i.e., solution to
`R` **`lambert_wm1`**`(T x)`<br>\newline
Implementation of the $W_{-1}$ branch of the Lambert W function, i.e., solution to the function $W_{-1}(x) \exp^{W_{-1}(x)} = x$
{{< since 2.25 >}}
+
+## Hypergeometric Functions {#hypergeometric-functions}
+
+Hypergeometric functions refer to a power series of the form
+\begin{equation*}
+_pF_q(a_1,...,a_p;b_1,...,b_q;z) = \sum_{n=0}^\infty \frac{(a_1)_n\cdot\cdot\cdot(a_p)_n}{(b_1)_n\cdot\cdot\cdot(b_q)_n} \frac{x^n}{n!}
+\end{equation*}
+where $(a)_n$ is the Pochhammer symbol defined as $(a)_n = \frac{\Gamma(a+n)}{\Gamma(a)}$.
+
+The gradients of the the hypergeometric function are given by:
+\begin{equation*}
+ \frac{\partial }{\partial a_1} =
+ \sum_{k=0}^{\infty}{
+ \frac
+ {\psi\left(k+a_1\right)\left(\prod_{j=1}^p\left(a_j\right)_k\right)z^k}
+ {k!\prod_{j=1}^q\left(b_j\right)_k}}
+ - \psi\left(a_1\right){}_pF_q(a_1,...,a_p;b_1,...,b_q;z)
+\end{equation*}
+\begin{equation*}
+ \frac{\partial }{\partial b_1} =
+ \psi\left(b_1\right){}_pF_q(a_1,...,a_p;b_1,...,b_q;z) -
+ \sum_{k=0}^{\infty}{
+ \frac
+ {\psi\left(k+b_1\right)\left(\prod_{j=1}^p\left(a_j\right)_k\right)z^k}
+ {k!\prod_{j=1}^q\left(b_j\right)_k}}
+ \end{equation*}
+\begin{equation*}
+ \frac{\partial }{\partial z} =
+ \frac{\prod_{j=1}^{p}a_j}{\prod_{j=1}^{q} b_j}\
+ {}_pF_q(a_1+1,...,a_p+1;b_1+1,...,b_q+1;z)
+\end{equation*}
+
+Stan provides both the generalized hypergeometric function as well as several
+special cases for particular values of p and q.
+
+<!-- real; hypergeometric_1F0; (real a, real z); -->
+\index{{\tt \bfseries hypergeometric\_1F0 }!{\tt (real a, real z): real}|hyperpage}
+
+`real` **`hypergeometric_1F0`**`(real a, real z)`<br>\newline
+Special case of the hypergeometric function with $p=1$ and $q=0$.
+{{< since 2.37 >}}
+
+<!-- real; hypergeometric_2F1; (real a1, real a2, real b1, real z); -->
+\index{{\tt \bfseries hypergeometric\_2F1 }!{\tt (real a1, real a2, real b1, real z): real}|hyperpage}
+
+`real` **`hypergeometric_2F1`**`(real a1, real a2, real b1, real z)`<br>\newline
+Special case of the hypergeometric function with $p=2$ and $q=1$.
+{{< since 2.37 >}}
+
+<!-- real; hypergeometric_3F2; (T1 a, T2 b, real z); -->
+\index{{\tt \bfseries hypergeometric\_3F2 }!{\tt (T1 a, T2 b, real z): real}|hyperpage}
+
+`real` **`hypergeometric_3F2`**`(T1 a, T2 b, real z)`<br>\newline
+Special case of the hypergeometric function with $p=3$ and $q=2$, where a and b are vectors of length 3 and 2, respectively.
+{{< since 2.37 >}}
+
+<!-- real; hypergeometric_pFq; (T1 a, T2 b, real z); -->
+\index{{\tt \bfseries hypergeometric\_pFq }!{\tt (T1 a, T2 b, real z): real}|hyperpage}
+
+`real` **`hypergeometric_pFq`**`(T1 a, T2 b, real z)`<br>\newline
+Generalized hypergeometric function, where a and b are vectors of length p and q, respectively.
+{{< since 2.37 >}}
From 761548bc794460b357531ff3626e09952b0469b0 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <andrew.johnson@arjohnsonau.com>
Date: Sat, 22 Mar 2025 20:31:15 +0800
Subject: [PATCH 2/3] Typos and rendering issues
---
src/functions-reference/functions_index.qmd | 20 +++++++++++++++++++
.../real-valued_basic_functions.qmd | 7 +++----
2 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd
index abb0de6cf..277b4e516 100644
--- a/src/functions-reference/functions_index.qmd
+++ b/src/functions-reference/functions_index.qmd
@@ -1306,6 +1306,21 @@ pagetitle: Alphabetical Index
- <div class='index-container'>[distribution statement](bounded_discrete_distributions.qmd#index-entry-2fc02e8425e812e91f8ef47c9f53bd538c248cbd) <span class='detail'>(bounded_discrete_distributions.html)</span></div>
+<a id='hypergeometric_1F0' href='#hypergeometric_1F0' class='anchored unlink'>**hypergeometric_1F0**:</a>
+
+ - <div class='index-container'>[`(real a, real z) : real`](real-valued_basic_functions.qmd#index-entry-e29b2c1e8db395e7d15862eb2f1f1e63ac58b10f) <span class='detail'>(real-valued_basic_functions.html)</span></div>
+
+
+<a id='hypergeometric_2F1' href='#hypergeometric_2F1' class='anchored unlink'>**hypergeometric_2F1**:</a>
+
+ - <div class='index-container'>[`(real a1, real a2, real b1, real z) : real`](real-valued_basic_functions.qmd#index-entry-4ebcc0750c9365f9fd711bbd07b560cd76a3c016) <span class='detail'>(real-valued_basic_functions.html)</span></div>
+
+
+<a id='hypergeometric_3F2' href='#hypergeometric_3F2' class='anchored unlink'>**hypergeometric_3F2**:</a>
+
+ - <div class='index-container'>[`(T1 a, T2 b, real z) : real`](real-valued_basic_functions.qmd#index-entry-f578817f233389fabf92d2db8bcfc1878fec4eca) <span class='detail'>(real-valued_basic_functions.html)</span></div>
+
+
<a id='hypergeometric_lpmf' href='#hypergeometric_lpmf' class='anchored unlink'>**hypergeometric_lpmf**:</a>
- <div class='index-container'>[`(int n | int N, int a, int b) : real`](bounded_discrete_distributions.qmd#index-entry-74678ac15a9ad9dc38759c7f81421cd6abe7f8e8) <span class='detail'>(bounded_discrete_distributions.html)</span></div>
@@ -1316,6 +1331,11 @@ pagetitle: Alphabetical Index
- <div class='index-container'>[`(int n | int N, int a, int b) : real`](bounded_discrete_distributions.qmd#index-entry-bd50c4360d03f67c2f750c84c2b4b7f53ade58e9) <span class='detail'>(bounded_discrete_distributions.html)</span></div>
+<a id='hypergeometric_pFq' href='#hypergeometric_pFq' class='anchored unlink'>**hypergeometric_pFq**:</a>
+
+ - <div class='index-container'>[`(T1 a, T2 b, real z) : real`](real-valued_basic_functions.qmd#index-entry-2177c85f2269dea084da1c4e5b2a6f52c3337579) <span class='detail'>(real-valued_basic_functions.html)</span></div>
+
+
<a id='hypergeometric_rng' href='#hypergeometric_rng' class='anchored unlink'>**hypergeometric_rng**:</a>
- <div class='index-container'>[`(int N, int a, int2 b) : int`](bounded_discrete_distributions.qmd#index-entry-b7d868252dbebe75b731f601d6af7252a228c9bb) <span class='detail'>(bounded_discrete_distributions.html)</span></div>
diff --git a/src/functions-reference/real-valued_basic_functions.qmd b/src/functions-reference/real-valued_basic_functions.qmd
index ab4950b76..e549090e2 100644
--- a/src/functions-reference/real-valued_basic_functions.qmd
+++ b/src/functions-reference/real-valued_basic_functions.qmd
@@ -1707,7 +1707,7 @@ _pF_q(a_1,...,a_p;b_1,...,b_q;z) = \sum_{n=0}^\infty \frac{(a_1)_n\cdot\cdot\cdo
\end{equation*}
where $(a)_n$ is the Pochhammer symbol defined as $(a)_n = \frac{\Gamma(a+n)}{\Gamma(a)}$.
-The gradients of the the hypergeometric function are given by:
+The gradients of the hypergeometric function are given by:
\begin{equation*}
\frac{\partial }{\partial a_1} =
\sum_{k=0}^{\infty}{
@@ -1723,11 +1723,10 @@ The gradients of the the hypergeometric function are given by:
\frac
{\psi\left(k+b_1\right)\left(\prod_{j=1}^p\left(a_j\right)_k\right)z^k}
{k!\prod_{j=1}^q\left(b_j\right)_k}}
- \end{equation*}
+\end{equation*}
\begin{equation*}
\frac{\partial }{\partial z} =
- \frac{\prod_{j=1}^{p}a_j}{\prod_{j=1}^{q} b_j}\
- {}_pF_q(a_1+1,...,a_p+1;b_1+1,...,b_q+1;z)
+ \frac{\prod_{j=1}^{p}a_j}{\prod_{j=1}^{q} b_j}{}_pF_q(a_1+1,...,a_p+1;b_1+1,...,b_q+1;z)
\end{equation*}
Stan provides both the generalized hypergeometric function as well as several
From 708a5b82f213fb2620e2f0559fbb748eeb54faa8 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <andrew.johnson@arjohnsonau.com>
Date: Sat, 22 Mar 2025 20:47:40 +0800
Subject: [PATCH 3/3] Missed doc of Euler transform
---
src/functions-reference/real-valued_basic_functions.qmd | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/src/functions-reference/real-valued_basic_functions.qmd b/src/functions-reference/real-valued_basic_functions.qmd
index e549090e2..472405d8e 100644
--- a/src/functions-reference/real-valued_basic_functions.qmd
+++ b/src/functions-reference/real-valued_basic_functions.qmd
@@ -1743,7 +1743,12 @@ Special case of the hypergeometric function with $p=1$ and $q=0$.
\index{{\tt \bfseries hypergeometric\_2F1 }!{\tt (real a1, real a2, real b1, real z): real}|hyperpage}
`real` **`hypergeometric_2F1`**`(real a1, real a2, real b1, real z)`<br>\newline
-Special case of the hypergeometric function with $p=2$ and $q=1$.
+Special case of the hypergeometric function with $p=2$ and $q=1$. If the function does not
+meet convergence criteria for given inputs, the function will attempt to apply [Euler's transformation](https://mathworld.wolfram.com/EulersHypergeometricTransformations.html)
+to improve convergence:
+\begin{equation*}
+{}_2F_1(a_1,a_2, b_1, z)={}_2F_1(b_1 - a_1,a_2, b_1, \frac{z}{z-1})\cdot(1-z)^{-a_2}
+\end{equation*}
{{< since 2.37 >}}
<!-- real; hypergeometric_3F2; (T1 a, T2 b, real z); -->