scico.scipy.special#
BlockArray-compatible jax.scipy.special
functions.
This modules is a wrapper for jax.scipy.special where some
functions have been extended to automatically map over block array
blocks as described in NumPy and SciPy Functions.
Functions
|
Regularized incomplete beta function. |
|
The digamma function. |
|
Elementwise function for computing entropy. |
|
Returns the error function of complex argument. |
|
Complementary error function, |
|
Inverse of the error function. |
|
Exponential integral E1. |
|
Expit (a.k.a. |
|
gamma function. |
|
Regularized lower incomplete gamma function. |
|
Regularized upper incomplete gamma function. |
|
Logarithm of the absolute value of the gamma function. |
|
Modified Bessel function of order 0. |
|
Exponentially scaled modified Bessel function of order 0. |
|
Modified Bessel function of order 1. |
|
Exponentially scaled modified Bessel function of order 1. |
|
The associated Legendre functions (ALFs) of the first kind. |
|
The associated Legendre functions (ALFs) of the first kind. |
|
Returns the log of multivariate gamma, also sometimes called the |
|
Normal distribution function. |
|
The inverse of the CDF of the Normal distribution function. |
|
Polygamma functions. |
|
Spence's function, also known as the dilogarithm for real values. |
|
Computes the spherical harmonics. |
|
Riemann or Hurwitz zeta function. |
- scico.scipy.special.betainc(a, b, x)#
Regularized incomplete beta function.
LAX-backend implementation of
scipy.special.betainc.Original docstring below.
Computes the regularized incomplete beta function, defined as:
\[I_x(a, b) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)} \int_0^x t^{a-1}(1-t)^{b-1}dt,\]for \(0 \leq x \leq 1\).
- Parameters:
a (array_like) – Positive, real-valued parameters
b (array_like) – Positive, real-valued parameters
x (array_like) – Real-valued such that \(0 \leq x \leq 1\), the upper limit of integration
- Return type:
- Returns:
scalar or ndarray – Value of the regularized incomplete beta function
- scico.scipy.special.digamma(x)#
The digamma function.
LAX-backend implementation of
scipy.special.psi.The JAX version only accepts real-valued inputs.
Original docstring below.
The logarithmic derivative of the gamma function evaluated at
z.- Return type:
- Returns:
digamma (scalar or ndarray) – Computed values of
psi.
- scico.scipy.special.entr(x)#
Elementwise function for computing entropy.
LAX-backend implementation of
scipy.special.entr.Original docstring below.
\[\begin{split}\text{entr}(x) = \begin{cases} - x \log(x) & x > 0 \\ 0 & x = 0 \\ -\infty & \text{otherwise} \end{cases}\end{split}\]- Parameters:
x (ndarray) – Input array.
- Return type:
- Returns:
res (scalar or ndarray) – The value of the elementwise entropy function at the given points x.
- scico.scipy.special.erf(x)#
Returns the error function of complex argument.
LAX-backend implementation of
scipy.special.erf.Note that the JAX version does not support complex inputs.
Original docstring below.
It is defined as
2/sqrt(pi)*integral(exp(-t**2), t=0..z).- Parameters:
x (ndarray) – Input array.
- Return type:
- Returns:
res (scalar or ndarray) – The values of the error function at the given points x.
- scico.scipy.special.erfc(x)#
Complementary error function,
1 - erf(x).LAX-backend implementation of
scipy.special.erfc.Original docstring below.
- Parameters:
x (array_like) – Real or complex valued argument
out (ndarray, optional) – Optional output array for the function results
- Return type:
- Returns:
scalar or ndarray – Values of the complementary error function
- scico.scipy.special.erfinv(x)#
Inverse of the error function.
LAX-backend implementation of
scipy.special.erfinv.Original docstring below.
Computes the inverse of the error function.
In the complex domain, there is no unique complex number w satisfying erf(w)=z. This indicates a true inverse function would be multivalued. When the domain restricts to the real, -1 < x < 1, there is a unique real number satisfying erf(erfinv(x)) = x.
- Return type:
- Returns:
erfinv (scalar or ndarray) – The inverse of erf of y, element-wise
- scico.scipy.special.exp1(x, module='scipy.special')#
Exponential integral E1.
LAX-backend implementation of
scipy.special.exp1.Original docstring below.
For complex \(z \ne 0\) the exponential integral can be defined as
\[E_1(z) = \int_z^\infty \frac{e^{-t}}{t} dt,\]where the path of the integral does not cross the negative real axis or pass through the origin.
- Return type:
- Returns:
scalar or ndarray – Values of the exponential integral E1
- scico.scipy.special.expit(x)#
Expit (a.k.a. logistic sigmoid) ufunc for ndarrays.
LAX-backend implementation of
scipy.special.expit.Original docstring below.
The expit function, also known as the logistic sigmoid function, is defined as
expit(x) = 1/(1+exp(-x)). It is the inverse of the logit function.- Parameters:
x (ndarray) – The ndarray to apply expit to element-wise.
out (ndarray, optional) – Optional output array for the function values
- Return type:
- Returns:
scalar or ndarray – An ndarray of the same shape as x. Its entries are expit of the corresponding entry of x.
- scico.scipy.special.gamma(x)#
gamma function.
LAX-backend implementation of
scipy.special.gamma.The JAX version only accepts real-valued inputs.
Original docstring below.
The gamma function is defined as
\[\Gamma(z) = \int_0^\infty t^{z-1} e^{-t} dt\]for \(\Re(z) > 0\) and is extended to the rest of the complex plane by analytic continuation. See NIST DLMF for more details.
- Return type:
- Returns:
scalar or ndarray – Values of the gamma function
- scico.scipy.special.gammainc(a, x)#
Regularized lower incomplete gamma function.
LAX-backend implementation of
scipy.special.gammainc.Original docstring below.
It is defined as
\[P(a, x) = \frac{1}{\Gamma(a)} \int_0^x t^{a - 1}e^{-t} dt\]for \(a > 0\) and \(x \geq 0\).
- Parameters:
a (array_like) – Positive parameter
x (array_like) – Nonnegative argument
out (ndarray, optional) – Optional output array for the function values
- Return type:
- Returns:
scalar or ndarray – Values of the lower incomplete gamma function
- scico.scipy.special.gammaincc(a, x)#
Regularized upper incomplete gamma function.
LAX-backend implementation of
scipy.special.gammaincc.Original docstring below.
It is defined as
\[Q(a, x) = \frac{1}{\Gamma(a)} \int_x^\infty t^{a - 1}e^{-t} dt\]for \(a > 0\) and \(x \geq 0\).
- Parameters:
a (array_like) – Positive parameter
x (array_like) – Nonnegative argument
out (ndarray, optional) – Optional output array for the function values
- Return type:
- Returns:
scalar or ndarray – Values of the upper incomplete gamma function
- scico.scipy.special.gammaln(x)#
Logarithm of the absolute value of the gamma function.
LAX-backend implementation of
scipy.special.gammaln.Original docstring below.
Defined as
\[\ln(\lvert\Gamma(x)\rvert)\]where \(\Gamma\) is the gamma function. For more details on the gamma function, see NIST DLMF.
- Parameters:
x (array_like) – Real argument
- Return type:
- Returns:
scalar or ndarray – Values of the log of the absolute value of gamma
- scico.scipy.special.i0(x)#
Modified Bessel function of order 0.
LAX-backend implementation of
scipy.special.i0.Original docstring below.
Defined as,
\[I_0(x) = \sum_{k=0}^\infty \frac{(x^2/4)^k}{(k!)^2} = J_0(\imath x),\]where \(J_0\) is the Bessel function of the first kind of order 0.
- Parameters:
x (array_like) – Argument (float)
- Return type:
- Returns:
I (scalar or ndarray) – Value of the modified Bessel function of order 0 at x.
- scico.scipy.special.i0e(x)#
Exponentially scaled modified Bessel function of order 0.
LAX-backend implementation of
scipy.special.i0e.Original docstring below.
Defined as:
i0e(x) = exp(-abs(x)) * i0(x).
- Parameters:
x (array_like) – Argument (float)
- Return type:
- Returns:
I (scalar or ndarray) – Value of the exponentially scaled modified Bessel function of order 0 at x.
- scico.scipy.special.i1(x)#
Modified Bessel function of order 1.
LAX-backend implementation of
scipy.special.i1.Original docstring below.
Defined as,
\[I_1(x) = \frac{1}{2}x \sum_{k=0}^\infty \frac{(x^2/4)^k}{k! (k + 1)!} = -\imath J_1(\imath x),\]where \(J_1\) is the Bessel function of the first kind of order 1.
- Parameters:
x (array_like) – Argument (float)
- Return type:
- Returns:
I (scalar or ndarray) – Value of the modified Bessel function of order 1 at x.
- scico.scipy.special.i1e(x)#
Exponentially scaled modified Bessel function of order 1.
LAX-backend implementation of
scipy.special.i1e.Original docstring below.
Defined as:
i1e(x) = exp(-abs(x)) * i1(x)
- Parameters:
x (array_like) – Argument (float)
- Return type:
- Returns:
I (scalar or ndarray) – Value of the exponentially scaled modified Bessel function of order 1 at x.
- scico.scipy.special.lpmn(m, n, z)#
The associated Legendre functions (ALFs) of the first kind.
- Parameters:
m (
int) – The maximum order of the associated Legendre functions.n (
int) – The maximum degree of the associated Legendre function, often called l in describing ALFs. Both the degrees and orders are [0, 1, 2, …, l_max], where l_max denotes the maximum degree.z (
Array) – A vector of type float32 or float64 containing the sampling points at which the ALFs are computed.
- Return type:
- Returns:
A 2-tuple of 3D arrays of shape (l_max + 1, l_max + 1, len(z)) containing the values and derivatives of the associated Legendre functions of the first kind. The return type matches the type of z.
- Raises:
TypeError if elements of array z are not in (float32, float64). –
ValueError if array z is not 1D. –
NotImplementedError if m!=n. –
- scico.scipy.special.lpmn_values(m, n, z, is_normalized)#
The associated Legendre functions (ALFs) of the first kind.
Unlike lpmn, this function only computes the values of ALFs. The ALFs of the first kind can be used in spherical harmonics. The spherical harmonic of degree l and order m can be written as \(Y_l^m(\theta, \phi) = N_l^m * P_l^m(\cos \theta) * \exp(i m \phi)\), where \(N_l^m\) is the normalization factor and θ and φ are the colatitude and longitude, repectively. \(N_l^m\) is chosen in the way that the spherical harmonics form a set of orthonormal basis function of \(L^2(S^2)\). Normalizing \(P_l^m\) avoids overflow/underflow and achieves better numerical stability.
- Parameters:
m (
int) – The maximum order of the associated Legendre functions.n (
int) – The maximum degree of the associated Legendre function, often called l in describing ALFs. Both the degrees and orders are [0, 1, 2, …, l_max], where l_max denotes the maximum degree.z (
Array) – A vector of type float32 or float64 containing the sampling points at which the ALFs are computed.is_normalized (
bool) – True if the associated Legendre functions are normalized. With normalization, \(N_l^m\) is applied such that the spherical harmonics form a set of orthonormal basis functions of \(L^2(S^2)\).
- Return type:
- Returns:
A 3D array of shape (l_max + 1, l_max + 1, len(z)) containing the values of the associated Legendre functions of the first kind. The return type matches the type of z.
- Raises:
TypeError if elements of array z are not in (float32, float64). –
ValueError if array z is not 1D. –
NotImplementedError if m!=n. –
- scico.scipy.special.multigammaln(a, d)#
Returns the log of multivariate gamma, also sometimes called the
LAX-backend implementation of
scipy.special._spfun_stats.multigammaln.Original docstring below.
generalized gamma.
- scico.scipy.special.ndtr(x)#
Normal distribution function.
Returns the area under the Gaussian probability density function, integrated from minus infinity to x:
\[\begin{split}\begin{align} \mathrm{ndtr}(x) =& \ \frac{1}{\sqrt{2 \pi}}\int_{-\infty}^{x} e^{-\frac{1}{2}t^2} dt \\ =&\ \frac{1}{2} (1 + \mathrm{erf}(\frac{x}{\sqrt{2}})) \\ =&\ \frac{1}{2} \mathrm{erfc}(\frac{x}{\sqrt{2}}) \end{align}\end{split}\]
- scico.scipy.special.ndtri(p)#
The inverse of the CDF of the Normal distribution function.
Returns x such that the area under the PDF from \(-\infty\) to x is equal to p.
A piece-wise rational approximation is done for the function. This is a based on the implementation in netlib.
- scico.scipy.special.polygamma(n, x)#
Polygamma functions.
LAX-backend implementation of
scipy.special.polygamma.Original docstring below.
Defined as \(\psi^{(n)}(x)\) where \(\psi\) is the digamma function.
- Parameters:
n (array_like) – The order of the derivative of the digamma function; must be integral
x (array_like) – Real valued input
- Return type:
- Returns:
ndarray – Function results
- scico.scipy.special.spence(x)#
Spence’s function, also known as the dilogarithm for real values. It is defined to be:
\[\begin{equation} \int_1^z \frac{\log(t)}{1 - t}dt \end{equation}\]Unlike the SciPy implementation, this is only defined for positive real values of z. For negative values, NaN is returned.
- Parameters:
z – An array of type float32, float64.
- Return type:
- Returns:
An array with dtype=z.dtype. computed values of Spence’s function.
- Raises:
TypeError – if elements of array z are not in (float32, float64).
Notes: There is a different convention which defines Spence’s function by the integral:
\[\begin{equation} -\int_0^z \frac{\log(1 - t)}{t}dt \end{equation}\]this is our spence(1 - z).
- scico.scipy.special.sph_harm(m, n, theta, phi, n_max=None)#
Computes the spherical harmonics.
The JAX version has one extra argument n_max, the maximum value in n.
The spherical harmonic of degree n and order m can be written as \(Y_n^m(\theta, \phi) = N_n^m * P_n^m(\cos \phi) * \exp(i m \theta)\), where \(N_n^m = \sqrt{\frac{\left(2n+1\right) \left(n-m\right)!} {4 \pi \left(n+m\right)!}}\) is the normalization factor and \(\phi\) and \(\theta\) are the colatitude and longitude, repectively. \(N_n^m\) is chosen in the way that the spherical harmonics form a set of orthonormal basis functions of \(L^2(S^2)\).
- Parameters:
m (
Array) – The order of the harmonic; must have |m| <= n. Return values for |m| > n ara undefined.n (
Array) – The degree of the harmonic; must have n >= 0. The standard notation for degree in descriptions of spherical harmonics is l (lower case L). We use n here to be consistent with scipy.special.sph_harm. Return values for n < 0 are undefined.theta (
Array) – The azimuthal (longitudinal) coordinate; must be in [0, 2*pi].phi (
Array) – The polar (colatitudinal) coordinate; must be in [0, pi].n_max (
Optional[int]) – The maximum degree max(n). If the supplied n_max is not the true maximum value of n, the results are clipped to n_max. For example, sph_harm(m=jnp.array([2]), n=jnp.array([10]), theta, phi, n_max=6) acutually returns sph_harm(m=jnp.array([2]), n=jnp.array([6]), theta, phi, n_max=6)
- Return type:
- Returns:
A 1D array containing the spherical harmonics at (m, n, theta, phi).
- scico.scipy.special.zeta(x, q=None)#
Riemann or Hurwitz zeta function.
LAX-backend implementation of
scipy.special.zeta.Original docstring below.