torch.special

The torch.special module, modeled after SciPy’s special module.

This module is in BETA. New functions are still being added, and some functions may change in future PyTorch releases. See the documentation of each function for details.

Functions

torch.special.entr(input, *, out=None) → Tensor

Computes the entropy on input (as defined below), elementwise.

$$\begin{align} \text{entr(x)} = \begin{cases} -x * \ln(x) & x > 0 \\ 0 & x = 0.0 \\ -\infty & x < 0 \end{cases} \end{align}$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example::

>>> 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

Computes the error function of input. The error function is defined as follows:

$$\mathrm{erf}(x) = \frac{2}{\sqrt{\pi}} \int_{0}^{x} e^{-t^2} dt$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> torch.special.erf(torch.tensor([0, -1., 10.]))
tensor([ 0.0000, -0.8427,  1.0000])

torch.special.erfc(input, *, out=None) → Tensor

Computes the complementary error function of input. The complementary error function is defined as follows:

$$\mathrm{erfc}(x) = 1 - \frac{2}{\sqrt{\pi}} \int_{0}^{x} e^{-t^2} dt$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> torch.special.erfc(torch.tensor([0, -1., 10.]))
tensor([ 1.0000, 1.8427,  0.0000])

torch.special.erfinv(input, *, out=None) → Tensor

Computes the inverse error function of input. The inverse error function is defined in the range $(-1, 1)$ as:

$$\mathrm{erfinv}(\mathrm{erf}(x)) = x$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> torch.special.erfinv(torch.tensor([0, 0.5, -1.]))
tensor([ 0.0000,  0.4769,    -inf])

torch.special.expit(input, *, out=None) → Tensor

Computes the expit (also known as the logistic sigmoid function) of the elements of input.

$$\text{out}_{i} = \frac{1}{1 + e^{-\text{input}_{i}}}$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> 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

Computes the exponential of the elements minus 1 of input.

$$y_{i} = e^{x_{i}} - 1$$

Note

This function provides greater precision than exp(x) - 1 for small values of x.

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> torch.special.expm1(torch.tensor([0, math.log(2.)]))
tensor([ 0.,  1.])

torch.special.exp2(input, *, out=None) → Tensor

Computes the base two exponential function of input.

$$y_{i} = 2^{x_{i}}$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> torch.special.exp2(torch.tensor([0, math.log2(2.), 3, 4]))
tensor([ 1.,  2.,  8., 16.])

torch.special.gammaln(input, *, out=None) → Tensor

Computes the natural logarithm of the absolute value of the gamma function on input.

$$\text{out}_{i} = \ln \Gamma(|\text{input}_{i}|)$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> a = torch.arange(0.5, 2, 0.5)
>>> torch.special.gammaln(a)
tensor([ 0.5724,  0.0000, -0.1208])

torch.special.i0e(input, *, out=None) → Tensor

Computes the exponentially scaled zeroth order modified Bessel function of the first kind (as defined below) for each element of input.

$$\text{out}_{i} = \exp(-|x|) * i0(x) = \exp(-|x|) * \sum_{k=0}^{\infty} \frac{(\text{input}_{i}^2/4)^k}{(k!)^2}$$

Parameters

input (Tensor) – the input tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example::

>>> torch.special.i0e(torch.arange(5, dtype=torch.float32))
tensor([1.0000, 0.4658, 0.3085, 0.2430, 0.2070])

torch.special.logit(input, eps=None, *, out=None) → Tensor

Returns a new tensor with the logit of the elements of input. input is clamped to [eps, 1 - eps] when eps is not None. When eps is None and input < 0 or input > 1, the function will yields 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}$$

Parameters

• input (Tensor) – the input tensor.

• eps (float, optional) – the epsilon for input clamp bound. Default: None

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> 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.xlog1py(input, other, *, out=None) → Tensor

Computes input * log1p(other) with the following cases.

$$\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}$$

Similar to SciPy’s scipy.special.xlog1py.

Parameters

• input (Number or Tensor) – Multiplier

• other (Number or Tensor) – Argument

Note

At least one of input or other must be a tensor.

Keyword Arguments

out (Tensor, optional) – the output tensor.

Example:

>>> 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])