torch.special
torch.special 模块是基于 SciPy 的 special 模块。
函数
- torch.special.airy_ai(input, *, out=None) → Tensor
-
airy函数$\text{Ai}(\text{input})$。
- torch.special.bessel_j0(input, *, out=None) → Tensor
-
零阶第一类贝塞尔函数。
- torch.special.bessel_j1(input, *, out=None) → Tensor
-
第一类阶数为$1$的贝塞尔函数。
- torch.special.digamma(input, *, out=None) → Tensor
-
计算输入值的伽玛函数的对数导数。
$\digamma(x) = \frac{d}{dx} \ln\left(\Gamma\left(x\right)\right) = \frac{\Gamma'(x)}{\Gamma(x)}$注意
此函数类似于 SciPy 的 scipy.special.digamma。
注意
从 PyTorch 1.8 版本开始，当 digamma 函数的输入为 0 时，返回值为 -Inf。此前，对于相同的输入，它会返回 NaN。
示例：
>>> a = torch.tensor([1, 0.5]) >>> torch.special.digamma(a) tensor([-0.5772, -1.9635])
- torch.special.entr(input, *, out=None) → Tensor
-
逐元素计算
input（如下定义）的熵。$\begin{align} \text{entr(x)} = \begin{cases} -x * \ln(x) & x > 0 \\ 0 & x = 0.0 \\ -\infty & x < 0 \end{cases} \end{align}$- 示例:
-
>>> a = torch.arange(-0.5, 1, 0.5) >>> a tensor([-0.5000, 0.0000, 0.5000]) >>> torch.special.entr(a) tensor([ -inf, 0.0000, 0.3466])
- torch.special.erf(input, *, out=None) → Tensor
-
计算
input的误差函数，其定义如下：$\mathrm{erf}(x) = \frac{2}{\sqrt{\pi}} \int_{0}^{x} e^{-t^2} dt$示例：
>>> torch.special.erf(torch.tensor([0, -1., 10.])) tensor([ 0.0000, -0.8427, 1.0000])
- torch.special.erfc(input, *, out=None) → Tensor
-
计算
input的互补误差函数。互补误差函数定义如下：$\mathrm{erfc}(x) = 1 - \frac{2}{\sqrt{\pi}} \int_{0}^{x} e^{-t^2} dt$示例：
>>> torch.special.erfc(torch.tensor([0, -1., 10.])) tensor([ 1.0000, 1.8427, 0.0000])
- torch.special.erfcx(input, *, out=None) → Tensor
-
计算
input中每个元素的缩放互补误差函数。缩放互补误差函数定义为：$\mathrm{erfcx}(x) = e^{x^2} \mathrm{erfc}(x)$示例：
>>> torch.special.erfcx(torch.tensor([0, -1., 10.])) tensor([ 1.0000, 5.0090, 0.0561])
- torch.special.erfinv(input, *, out=None) → Tensor
-
计算
input的逆误差函数。逆误差函数的定义范围是$(-1, 1)$：$\mathrm{erfinv}(\mathrm{erf}(x)) = x$示例：
>>> torch.special.erfinv(torch.tensor([0, 0.5, -1.])) tensor([ 0.0000, 0.4769, -inf])
- torch.special.exp2(input, *, out=None) → Tensor
-
计算
input的以2为底的指数函数。$y_{i} = 2^{x_{i}}$示例：
>>> torch.special.exp2(torch.tensor([0, math.log2(2.), 3, 4])) tensor([ 1., 2., 8., 16.])
- torch.special.expit(input, *, out=None) → Tensor
-
计算
input元素的expit（也即逻辑 sigmond 函数）。$\text{out}_{i} = \frac{1}{1 + e^{-\text{input}_{i}}}$示例：
>>> t = torch.randn(4) >>> t tensor([ 0.9213, 1.0887, -0.8858, -1.7683]) >>> torch.special.expit(t) tensor([ 0.7153, 0.7481, 0.2920, 0.1458])
- torch.special.expm1(input, *, out=None) → Tensor
-
计算
input中每个元素减1后的指数值。$y_{i} = e^{x_{i}} - 1$注意
对于小数值的 x，此函数提供的精度高于 exp(x) - 1。
示例：
>>> torch.special.expm1(torch.tensor([0, math.log(2.)])) tensor([ 0., 1.])
- torch.special.gammainc(input, other, *, out=None) → Tensor
-
计算正则化的下不完全伽玛函数:
$\text{out}_{i} = \frac{1}{\Gamma(\text{input}_i)} \int_0^{\text{other}_i} t^{\text{input}_i-1} e^{-t} dt$其中 $\text{input}_i$ 和 $\text{other}_i$ 都是非负数，并且至少有一个是正数。如果两者都为零或其中一个为负数，则$\text{out}_i=\text{nan}$。$\Gamma(\cdot)$ 在上述方程中表示伽马函数。
$\Gamma(\text{input}_i) = \int_0^\infty t^{(\text{input}_i-1)} e^{-t} dt.$参见
torch.special.gammaincc()和torch.special.gammaln()以获取相关函数。支持广播到公共形状以及浮点输入。
注意
关于
input的反向传播目前还不支持。请在 PyTorch 的 Github 上提出一个请求，要求添加此功能。示例：
>>> a1 = torch.tensor([4.0]) >>> a2 = torch.tensor([3.0, 4.0, 5.0]) >>> a = torch.special.gammaincc(a1, a2) tensor([0.3528, 0.5665, 0.7350]) tensor([0.3528, 0.5665, 0.7350]) >>> b = torch.special.gammainc(a1, a2) + torch.special.gammaincc(a1, a2) tensor([1., 1., 1.])
- torch.special.gammaincc(x, y, *, out=None) → Tensor
-
计算正则化上不完整的伽玛函数:
$\text{out}_{i} = \frac{1}{\Gamma(\text{input}_i)} \int_{\text{other}_i}^{\infty} t^{\text{input}_i-1} e^{-t} dt$其中 $\text{input}_i$ 和 $\text{other}_i$ 都是非负数，并且至少有一个是正数。如果两者都为零或其中一个为负数，则$\text{out}_i=\text{nan}$。$\Gamma(\cdot)$ 在上述方程中表示伽马函数。
$\Gamma(\text{input}_i) = \int_0^\infty t^{(\text{input}_i-1)} e^{-t} dt.$参见
torch.special.gammainc()和torch.special.gammaln()以获取相关函数。支持广播到公共形状以及浮点输入。
注意
关于
input的反向传播目前还不支持。请在 PyTorch 的 Github 上提出一个请求，要求添加此功能。示例：
>>> a1 = torch.tensor([4.0]) >>> a2 = torch.tensor([3.0, 4.0, 5.0]) >>> a = torch.special.gammaincc(a1, a2) tensor([0.6472, 0.4335, 0.2650]) >>> b = torch.special.gammainc(a1, a2) + torch.special.gammaincc(a1, a2) tensor([1., 1., 1.])
- torch.special.gammaln(input, *, out=None) → Tensor
-
计算输入张量的伽玛函数绝对值的自然对数。
$\text{out}_{i} = \ln \Gamma(|\text{input}_{i}|)$示例：
>>> a = torch.arange(0.5, 2, 0.5) >>> torch.special.gammaln(a) tensor([ 0.5724, 0.0000, -0.1208])
- torch.special.i0(input, *, out=None) → Tensor
-
计算
input中每个元素的第一类零阶 modified Bessel 函数。$\text{out}_{i} = I_0(\text{input}_{i}) = \sum_{k=0}^{\infty} \frac{(\text{input}_{i}^2/4)^k}{(k!)^2}$示例：
>>> torch.i0(torch.arange(5, dtype=torch.float32)) tensor([ 1.0000, 1.2661, 2.2796, 4.8808, 11.3019])
- torch.special.i0e(input, *, out=None) → Tensor
-
计算
input中每个元素的第一类修正贝塞尔函数的零阶指数缩放值（如下定义）。$\text{out}_{i} = \exp(-|x|) * i0(x) = \exp(-|x|) * \sum_{k=0}^{\infty} \frac{(\text{input}_{i}^2/4)^k}{(k!)^2}$- 示例:
-
>>> torch.special.i0e(torch.arange(5, dtype=torch.float32)) tensor([1.0000, 0.4658, 0.3085, 0.2430, 0.2070])
- torch.special.i1(input, *, out=None) → Tensor
-
计算输入 tensor 中每个元素的第一类 modified Bessel 函数（如下定义）。
$\text{out}_{i} = \frac{(\text{input}_{i})}{2} * \sum_{k=0}^{\infty} \frac{(\text{input}_{i}^2/4)^k}{(k!) * (k+1)!}$- 示例:
-
>>> torch.special.i1(torch.arange(5, dtype=torch.float32)) tensor([0.0000, 0.5652, 1.5906, 3.9534, 9.7595])
- torch.special.i1e(input, *, out=None) → Tensor
-
计算每个元素的第一类修正贝塞尔函数的指数缩放版本（如下定义），其中输入为
input。$\text{out}_{i} = \exp(-|x|) * i1(x) = \exp(-|x|) * \frac{(\text{input}_{i})}{2} * \sum_{k=0}^{\infty} \frac{(\text{input}_{i}^2/4)^k}{(k!) * (k+1)!}$- 示例:
-
>>> torch.special.i1e(torch.arange(5, dtype=torch.float32)) tensor([0.0000, 0.2079, 0.2153, 0.1968, 0.1788])
- torch.special.log1p(input, *, out=None) → Tensor
-
别名：
torch.log1p()。
- torch.special.log_ndtr(input, *, out=None) → Tensor
-
计算从负无穷大到
input的标准化高斯概率密度函数下面积的对数，逐元素处理。$\text{log\_ndtr}(x) = \log\left(\frac{1}{\sqrt{2 \pi}}\int_{-\infty}^{x} e^{-\frac{1}{2}t^2} dt \right)$- 示例:
-
>>> torch.special.log_ndtr(torch.tensor([-3., -2, -1, 0, 1, 2, 3])) tensor([-6.6077 -3.7832 -1.841 -0.6931 -0.1728 -0.023 -0.0014])
- torch.special.log_softmax(input, dim, *, dtype=None) → Tensor
-
计算softmax，然后取对数。
虽然在数学上等同于 log(softmax(x))，但是分别进行这两个操作会更加缓慢且数值不稳。该函数的计算方式如下：
$\text{log\_softmax}(x_{i}) = \log\left(\frac{\exp(x_i) }{ \sum_j \exp(x_j)} \right)$- 参数
-
-
输入 (Tensor) – 输入张量
-
dim (int) – 指定用于计算对数软最大值的维度。
-
dtype (
torch.dtype, 可选) – 返回张量的数据类型。如果指定了dtype，则在执行操作之前将输入张量转换为指定的dtype，以防止数据溢出。默认值：None。
-
- 示例:
-
>>> t = torch.ones(2, 2) >>> torch.special.log_softmax(t, 0) tensor([[-0.6931, -0.6931], [-0.6931, -0.6931]])
- torch.special.logit(input, eps=None, *, out=None) → Tensor
-
返回一个包含
input元素的对数几率的新张量。当 eps 不为 None 时，input会被限制在 [eps, 1 - eps] 范围内。如果 eps 为 None 并且input<0 或者input>1，则函数将返回 NaN。$\begin{align} y_{i} &= \ln(\frac{z_{i}}{1 - z_{i}}) \\ z_{i} &= \begin{cases} x_{i} & \text{if eps is None} \\ \text{eps} & \text{if } x_{i} < \text{eps} \\ x_{i} & \text{if } \text{eps} \leq x_{i} \leq 1 - \text{eps} \\ 1 - \text{eps} & \text{if } x_{i} > 1 - \text{eps} \end{cases} \end{align}$- 参数
- 关键字参数
-
out (Tensor, 可选) – 指定输出张量。
示例：
>>> a = torch.rand(5) >>> a tensor([0.2796, 0.9331, 0.6486, 0.1523, 0.6516]) >>> torch.special.logit(a, eps=1e-6) tensor([-0.9466, 2.6352, 0.6131, -1.7169, 0.6261])
- torch.special.logsumexp(input, dim, keepdim=False, *, out=None)
-
别名 for
torch.logsumexp()。
- torch.special.multigammaln(input, p, *, out=None) → Tensor
-
计算维度为$p$的多元对数伽玛函数，元素级别定义如下：
$\log(\Gamma_{p}(a)) = C + \displaystyle \sum_{i=1}^{p} \log\left(\Gamma\left(a - \frac{i - 1}{2}\right)\right)$其中 $C = \log(\pi) \cdot \frac{p (p - 1)}{4}$，$\Gamma(-)$ 表示 Gamma 函数。
所有元素必须大于$\frac{p - 1}{2}$，否则行为不定。
示例：
>>> a = torch.empty(2, 3).uniform_(1, 2) >>> a tensor([[1.6835, 1.8474, 1.1929], [1.0475, 1.7162, 1.4180]]) >>> torch.special.multigammaln(a, 2) tensor([[0.3928, 0.4007, 0.7586], [1.0311, 0.3901, 0.5049]])
- torch.special.ndtr(input, *, out=None) → Tensor
-
计算从负无穷到
input的标准高斯概率密度函数的面积，逐元素进行。$\text{ndtr}(x) = \frac{1}{\sqrt{2 \pi}}\int_{-\infty}^{x} e^{-\frac{1}{2}t^2} dt$- 示例:
-
>>> torch.special.ndtr(torch.tensor([-3., -2, -1, 0, 1, 2, 3])) tensor([0.0013, 0.0228, 0.1587, 0.5000, 0.8413, 0.9772, 0.9987])
- torch.special.ndtri(input, *, out=None) → Tensor
-
计算参数 x，使得高斯概率密度函数从负无穷到 x 的积分结果等于
input，逐元素进行。$\text{ndtri}(p) = \sqrt{2}\text{erf}^{-1}(2p - 1)$注意
也称为正态分布的逆函数。
- 示例:
-
>>> torch.special.ndtri(torch.tensor([0, 0.25, 0.5, 0.75, 1])) tensor([ -inf, -0.6745, 0.0000, 0.6745, inf])
- torch.special.polygamma(n, input, *, out=None) → Tensor
-
计算输入张量的$n^{th}$阶聚伽马函数的导数。其中$n \geq 0$表示聚伽马函数的阶数。
$\psi^{(n)}(x) = \frac{d^{(n)}}{dx^{(n)}} \psi(x)$注意
此函数仅适用于非负整数 $n \geq 0$。
- 示例:
-
>>> a = torch.tensor([1, 0.5]) >>> torch.special.polygamma(1, a) tensor([1.64493, 4.9348]) >>> torch.special.polygamma(2, a) tensor([ -2.4041, -16.8288]) >>> torch.special.polygamma(3, a) tensor([ 6.4939, 97.4091]) >>> torch.special.polygamma(4, a) tensor([ -24.8863, -771.4742])
- torch.special.psi(input, *, out=None) → Tensor
-
别名 for
torch.special.digamma()。
- torch.special.round(input, *, out=None) → Tensor
-
别名 for
torch.round()。
- torch.special.scaled_modified_bessel_k0(input, *, out=None) → Tensor
-
阶数为$0$的第二类修正贝塞尔函数的缩放版本。
- torch.special.scaled_modified_bessel_k1(input, *, out=None) → Tensor
-
第二类修正贝塞尔函数，阶数为$1$。
- torch.special.sinc(input, *, out=None) → Tensor
-
计算的归一化sinc值。
$\text{out}_{i} = \begin{cases} 1, & \text{if}\ \text{input}_{i}=0 \\ \sin(\pi \text{input}_{i}) / (\pi \text{input}_{i}), & \text{otherwise} \end{cases}$- 示例:
-
>>> t = torch.randn(4) >>> t tensor([ 0.2252, -0.2948, 1.0267, -1.1566]) >>> torch.special.sinc(t) tensor([ 0.9186, 0.8631, -0.0259, -0.1300])
- torch.special.softmax(input, dim, *, dtype=None) → Tensor
-
计算软最大函数。
softmax定义如下：
$\text{Softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_j \exp(x_j)}$
它会应用到dim维度上所有的切片，并将其重新缩放，使元素的值在[0, 1]范围内且总和为1。
- 参数
-
-
输入 (Tensor) – 输入张量
-
dim (int) – 计算 softmax 的维度。
-
dtype (
torch.dtype, 可选) – 返回张量的数据类型。如果指定了dtype，则在执行操作之前将输入张量转换为指定的dtype，以防止数据溢出。默认值：None。
-
- 示例:
-
>>> t = torch.ones(2, 2) >>> torch.special.softmax(t, 0) tensor([[0.5000, 0.5000], [0.5000, 0.5000]])
- torch.special.spherical_bessel_j0(input, *, out=None) → Tensor
-
零阶第一类球贝塞尔函数。
- torch.special.xlog1py(input, other, *, out=None) → Tensor
-
计算
input * log1p(other)，具体情况如下。$\text{out}_{i} = \begin{cases} \text{NaN} & \text{if } \text{other}_{i} = \text{NaN} \\ 0 & \text{if } \text{input}_{i} = 0.0 \text{ and } \text{other}_{i} != \text{NaN} \\ \text{input}_{i} * \text{log1p}(\text{other}_{i})& \text{otherwise} \end{cases}$类似于 SciPy 的 scipy.special.xlog1py 函数。
注意
至少
input和other中有一个必须是张量。- 关键字参数
-
out (Tensor, 可选) – 指定输出张量。
示例：
>>> x = torch.zeros(5,) >>> y = torch.tensor([-1, 0, 1, float('inf'), float('nan')]) >>> torch.special.xlog1py(x, y) tensor([0., 0., 0., 0., nan]) >>> x = torch.tensor([1, 2, 3]) >>> y = torch.tensor([3, 2, 1]) >>> torch.special.xlog1py(x, y) tensor([1.3863, 2.1972, 2.0794]) >>> torch.special.xlog1py(x, 4) tensor([1.6094, 3.2189, 4.8283]) >>> torch.special.xlog1py(2, y) tensor([2.7726, 2.1972, 1.3863])
- torch.special.xlogy(input, other, *, out=None) → Tensor
-
计算
input * log(other)，具体情况如下。$\text{out}_{i} = \begin{cases} \text{NaN} & \text{if } \text{other}_{i} = \text{NaN} \\ 0 & \text{if } \text{input}_{i} = 0.0 \\ \text{input}_{i} * \log{(\text{other}_{i})} & \text{otherwise} \end{cases}$与 SciPy 的 scipy.special.xlogy 类似。
注意
至少
input和other中有一个必须是张量。- 关键字参数
-
out (Tensor, 可选) – 指定输出张量。
示例：
>>> x = torch.zeros(5,) >>> y = torch.tensor([-1, 0, 1, float('inf'), float('nan')]) >>> torch.special.xlogy(x, y) tensor([0., 0., 0., 0., nan]) >>> x = torch.tensor([1, 2, 3]) >>> y = torch.tensor([3, 2, 1]) >>> torch.special.xlogy(x, y) tensor([1.0986, 1.3863, 0.0000]) >>> torch.special.xlogy(x, 4) tensor([1.3863, 2.7726, 4.1589]) >>> torch.special.xlogy(2, y) tensor([2.1972, 1.3863, 0.0000])
- torch.special.zeta(input, other, *, out=None) → Tensor
-
逐元素计算Hurwitz zeta函数。
$\zeta(x, q) = \sum_{k=0}^{\infty} \frac{1}{(k + q)^x}$注意
黎曼ζ函数对应于< cite > q = 1 < /cite >的情形
- 关键字参数
-
out (Tensor, 可选) – 指定输出张量。
- 示例:
-
>>> x = torch.tensor([2., 4.]) >>> torch.special.zeta(x, 1) tensor([1.6449, 1.0823]) >>> torch.special.zeta(x, torch.tensor([1., 2.])) tensor([1.6449, 0.0823]) >>> torch.special.zeta(2, torch.tensor([1., 2.])) tensor([1.6449, 0.6449])