class torch.distributions.lkj_cholesky.LKJCholesky(dim, concentration=1.0, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution LKJ distribution for lower Cholesky factor of correlation matrices. The distribution is controlled by concentration parameter η\eta  to make the probability of the correlation matrix MM  generated from a Cholesky factor propotional to det(M)η−1\det(M)^{\eta - 1} . Because of that, when concentration == 1, we have a uniform distribution over Cholesky factors of correlation matrices. Note that this distribution samples the Cholesky factor of correlation matrices and not the correlation matrices themselves and thereby differs slightly from the derivations in [1] for the LKJCorr distribution. For sampling, this uses the Onion method from [1] Section 3. L ~ LKJCholesky(dim, concentration) X = L @ L’ ~ LKJCorr(dim, concentration) Example: >>> l = LKJCholesky(3, 0.5)
>>> l.sample()  # l @ l.T is a sample of a correlation 3x3 matrix
tensor([[ 1.0000,  0.0000,  0.0000],
        [ 0.3516,  0.9361,  0.0000],
        [-0.1899,  0.4748,  0.8593]])
  Parameters

dimension (dim) – dimension of the matrices
concentration (float or Tensor) – concentration/shape parameter of the distribution (often referred to as eta)    References [1] Generating random correlation matrices based on vines and extended onion method, Daniel Lewandowski, Dorota Kurowicka, Harry Joe.
arg_constraints = {'concentration': GreaterThan(lower_bound=0.0)}

expand(batch_shape, _instance=None) [source]

log_prob(value) [source]

sample(sample_shape=torch.Size([])) [source]

support = CorrCholesky()


arg_constraints = {'concentration': GreaterThan(lower_bound=0.0)}


class torch.distributions.log_normal.LogNormal(loc, scale, validate_args=None) [source]

Bases: torch.distributions.transformed_distribution.TransformedDistribution Creates a log-normal distribution parameterized by loc and scale where: X ~ Normal(loc, scale)
Y = exp(X) ~ LogNormal(loc, scale)
 Example: >>> m = LogNormal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # log-normal distributed with mean=0 and stddev=1
tensor([ 0.1046])
  Parameters

loc (float or Tensor) – mean of log of distribution
scale (float or Tensor) – standard deviation of log of the distribution
arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

entropy() [source]

expand(batch_shape, _instance=None) [source]

has_rsample = True

property loc

property mean

property scale

support = GreaterThan(lower_bound=0.0)

property variance


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}


class torch.distributions.lowrank_multivariate_normal.LowRankMultivariateNormal(loc, cov_factor, cov_diag, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a multivariate normal distribution with covariance matrix having a low-rank form parameterized by cov_factor and cov_diag: covariance_matrix = cov_factor @ cov_factor.T + cov_diag
 Example >>> m = LowRankMultivariateNormal(torch.zeros(2), torch.tensor([[1.], [0.]]), torch.ones(2))
>>> m.sample()  # normally distributed with mean=`[0,0]`, cov_factor=`[[1],[0]]`, cov_diag=`[1,1]`
tensor([-0.2102, -0.5429])
  Parameters

loc (Tensor) – mean of the distribution with shape batch_shape + event_shape

cov_factor (Tensor) – factor part of low-rank form of covariance matrix with shape batch_shape + event_shape + (rank,)

cov_diag (Tensor) – diagonal part of low-rank form of covariance matrix with shape batch_shape + event_shape
     Note The computation for determinant and inverse of covariance matrix is avoided when cov_factor.shape[1] << cov_factor.shape[0] thanks to Woodbury matrix identity and matrix determinant lemma. Thanks to these formulas, we just need to compute the determinant and inverse of the small size “capacitance” matrix: capacitance = I + cov_factor.T @ inv(cov_diag) @ cov_factor

arg_constraints = {'cov_diag': IndependentConstraint(GreaterThan(lower_bound=0.0), 1), 'cov_factor': IndependentConstraint(Real(), 2), 'loc': IndependentConstraint(Real(), 1)}

covariance_matrix [source]

entropy() [source]

expand(batch_shape, _instance=None) [source]

has_rsample = True

log_prob(value) [source]

property mean

precision_matrix [source]

rsample(sample_shape=torch.Size([])) [source]

scale_tril [source]

support = IndependentConstraint(Real(), 1)

variance [source]


arg_constraints = {'cov_diag': IndependentConstraint(GreaterThan(lower_bound=0.0), 1), 'cov_factor': IndependentConstraint(Real(), 2), 'loc': IndependentConstraint(Real(), 1)}


support = IndependentConstraint(Real(), 1)


class torch.distributions.mixture_same_family.MixtureSameFamily(mixture_distribution, component_distribution, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution The MixtureSameFamily distribution implements a (batch of) mixture distribution where all component are from different parameterizations of the same distribution type. It is parameterized by a Categorical “selecting distribution” (over k component) and a component distribution, i.e., a Distribution with a rightmost batch shape (equal to [k]) which indexes each (batch of) component. Examples: # Construct Gaussian Mixture Model in 1D consisting of 5 equally
# weighted normal distributions
>>> mix = D.Categorical(torch.ones(5,))
>>> comp = D.Normal(torch.randn(5,), torch.rand(5,))
>>> gmm = MixtureSameFamily(mix, comp)

# Construct Gaussian Mixture Modle in 2D consisting of 5 equally
# weighted bivariate normal distributions
>>> mix = D.Categorical(torch.ones(5,))
>>> comp = D.Independent(D.Normal(
             torch.randn(5,2), torch.rand(5,2)), 1)
>>> gmm = MixtureSameFamily(mix, comp)

# Construct a batch of 3 Gaussian Mixture Models in 2D each
# consisting of 5 random weighted bivariate normal distributions
>>> mix = D.Categorical(torch.rand(3,5))
>>> comp = D.Independent(D.Normal(
            torch.randn(3,5,2), torch.rand(3,5,2)), 1)
>>> gmm = MixtureSameFamily(mix, comp)
  Parameters

mixture_distribution – torch.distributions.Categorical-like instance. Manages the probability of selecting component. The number of categories must match the rightmost batch dimension of the component_distribution. Must have either scalar batch_shape or batch_shape matching component_distribution.batch_shape[:-1]

component_distribution – torch.distributions.Distribution-like instance. Right-most batch dimension indexes component.
arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {}

cdf(x) [source]

property component_distribution

expand(batch_shape, _instance=None) [source]

has_rsample = False

log_prob(x) [source]

property mean

property mixture_distribution

sample(sample_shape=torch.Size([])) [source]

property support

property variance


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {}


class torch.distributions.multinomial.Multinomial(total_count=1, probs=None, logits=None, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a Multinomial distribution parameterized by total_count and either probs or logits (but not both). The innermost dimension of probs indexes over categories. All other dimensions index over batches. Note that total_count need not be specified if only log_prob() is called (see example below)  Note The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. attr:probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. attr:logits will return this normalized value.
sample() requires a single shared total_count for all parameters and samples.
log_prob() allows different total_count for each parameter and sample.  Example: >>> m = Multinomial(100, torch.tensor([ 1., 1., 1., 1.]))
>>> x = m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 21.,  24.,  30.,  25.])

>>> Multinomial(probs=torch.tensor([1., 1., 1., 1.])).log_prob(x)
tensor([-4.1338])
  Parameters

total_count (int) – number of trials
probs (Tensor) – event probabilities
logits (Tensor) – event log probabilities (unnormalized)
arg_constraints = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}

expand(batch_shape, _instance=None) [source]

log_prob(value) [source]

property logits

property mean

property param_shape

property probs

sample(sample_shape=torch.Size([])) [source]

property support

total_count: int = None

property variance


arg_constraints = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}


class torch.distributions.multivariate_normal.MultivariateNormal(loc, covariance_matrix=None, precision_matrix=None, scale_tril=None, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a multivariate normal (also called Gaussian) distribution parameterized by a mean vector and a covariance matrix. The multivariate normal distribution can be parameterized either in terms of a positive definite covariance matrix Σ\mathbf{\Sigma}  or a positive definite precision matrix Σ−1\mathbf{\Sigma}^{-1}  or a lower-triangular matrix L\mathbf{L}  with positive-valued diagonal entries, such that Σ=LL⊤\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top . This triangular matrix can be obtained via e.g. Cholesky decomposition of the covariance. Example >>> m = MultivariateNormal(torch.zeros(2), torch.eye(2))
>>> m.sample()  # normally distributed with mean=`[0,0]` and covariance_matrix=`I`
tensor([-0.2102, -0.5429])
  Parameters

loc (Tensor) – mean of the distribution
covariance_matrix (Tensor) – positive-definite covariance matrix
precision_matrix (Tensor) – positive-definite precision matrix
scale_tril (Tensor) – lower-triangular factor of covariance, with positive-valued diagonal     Note Only one of covariance_matrix or precision_matrix or scale_tril can be specified. Using scale_tril will be more efficient: all computations internally are based on scale_tril. If covariance_matrix or precision_matrix is passed instead, it is only used to compute the corresponding lower triangular matrices using a Cholesky decomposition.
arg_constraints = {'covariance_matrix': PositiveDefinite(), 'loc': IndependentConstraint(Real(), 1), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}

covariance_matrix [source]

entropy() [source]

expand(batch_shape, _instance=None) [source]

has_rsample = True

log_prob(value) [source]

property mean

precision_matrix [source]

rsample(sample_shape=torch.Size([])) [source]

scale_tril [source]

support = IndependentConstraint(Real(), 1)

property variance


arg_constraints = {'covariance_matrix': PositiveDefinite(), 'loc': IndependentConstraint(Real(), 1), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}


class torch.distributions.negative_binomial.NegativeBinomial(total_count, probs=None, logits=None, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a Negative Binomial distribution, i.e. distribution of the number of successful independent and identical Bernoulli trials before total_count failures are achieved. The probability of failure of each Bernoulli trial is probs.  Parameters

total_count (float or Tensor) – non-negative number of negative Bernoulli trials to stop, although the distribution is still valid for real valued count
probs (Tensor) – Event probabilities of failure in the half open interval [0, 1)
logits (Tensor) – Event log-odds for probabilities of failure
arg_constraints = {'logits': Real(), 'probs': HalfOpenInterval(lower_bound=0.0, upper_bound=1.0), 'total_count': GreaterThanEq(lower_bound=0)}

expand(batch_shape, _instance=None) [source]

log_prob(value) [source]

logits [source]

property mean

property param_shape

probs [source]

sample(sample_shape=torch.Size([])) [source]

support = IntegerGreaterThan(lower_bound=0)

property variance


arg_constraints = {'logits': Real(), 'probs': HalfOpenInterval(lower_bound=0.0, upper_bound=1.0), 'total_count': GreaterThanEq(lower_bound=0)}


class torch.distributions.normal.Normal(loc, scale, validate_args=None) [source]

Bases: torch.distributions.exp_family.ExponentialFamily Creates a normal (also called Gaussian) distribution parameterized by loc and scale. Example: >>> m = Normal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # normally distributed with loc=0 and scale=1
tensor([ 0.1046])
  Parameters

loc (float or Tensor) – mean of the distribution (often referred to as mu)
scale (float or Tensor) – standard deviation of the distribution (often referred to as sigma)
arg_constraints = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

cdf(value) [source]

entropy() [source]

expand(batch_shape, _instance=None) [source]

has_rsample = True

icdf(value) [source]

log_prob(value) [source]

property mean

rsample(sample_shape=torch.Size([])) [source]

sample(sample_shape=torch.Size([])) [source]

property stddev

support = Real()

property variance


arg_constraints = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}


class torch.distributions.one_hot_categorical.OneHotCategorical(probs=None, logits=None, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a one-hot categorical distribution parameterized by probs or logits. Samples are one-hot coded vectors of size probs.size(-1).  Note The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. attr:probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. attr:logits will return this normalized value.  See also: torch.distributions.Categorical() for specifications of probs and logits. Example: >>> m = OneHotCategorical(torch.tensor([ 0.25, 0.25, 0.25, 0.25 ]))
>>> m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 0.,  0.,  0.,  1.])
  Parameters

probs (Tensor) – event probabilities
logits (Tensor) – event log probabilities (unnormalized)
arg_constraints = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}

entropy() [source]

enumerate_support(expand=True) [source]

expand(batch_shape, _instance=None) [source]

has_enumerate_support = True

log_prob(value) [source]

property logits

property mean

property param_shape

property probs

sample(sample_shape=torch.Size([])) [source]

support = OneHot()

property variance


class torch.distributions.pareto.Pareto(scale, alpha, validate_args=None) [source]

Bases: torch.distributions.transformed_distribution.TransformedDistribution Samples from a Pareto Type 1 distribution. Example: >>> m = Pareto(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Pareto distribution with scale=1 and alpha=1
tensor([ 1.5623])
  Parameters

scale (float or Tensor) – Scale parameter of the distribution
alpha (float or Tensor) – Shape parameter of the distribution
arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'alpha': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}

entropy() [source]

expand(batch_shape, _instance=None) [source]

property mean

property support

property variance


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'alpha': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}


class torch.distributions.poisson.Poisson(rate, validate_args=None) [source]

Bases: torch.distributions.exp_family.ExponentialFamily Creates a Poisson distribution parameterized by rate, the rate parameter. Samples are nonnegative integers, with a pmf given by  rateke−ratek!\mathrm{rate}^k \frac{e^{-\mathrm{rate}}}{k!}
Example: >>> m = Poisson(torch.tensor([4]))
>>> m.sample()
tensor([ 3.])
  Parameters
rate (Number, Tensor) – the rate parameter
arg_constraints = {'rate': GreaterThan(lower_bound=0.0)}

expand(batch_shape, _instance=None) [source]

log_prob(value) [source]

property mean

sample(sample_shape=torch.Size([])) [source]

support = IntegerGreaterThan(lower_bound=0)

property variance


arg_constraints = {'rate': GreaterThan(lower_bound=0.0)}


class torch.distributions.relaxed_bernoulli.LogitRelaxedBernoulli(temperature, probs=None, logits=None, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a LogitRelaxedBernoulli distribution parameterized by probs or logits (but not both), which is the logit of a RelaxedBernoulli distribution. Samples are logits of values in (0, 1). See [1] for more details.  Parameters

temperature (Tensor) – relaxation temperature
probs (Number, Tensor) – the probability of sampling 1

logits (Number, Tensor) – the log-odds of sampling 1
    [1] The Concrete Distribution: A Continuous Relaxation of Discrete Random Variables (Maddison et al, 2017) [2] Categorical Reparametrization with Gumbel-Softmax (Jang et al, 2017)
arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}

expand(batch_shape, _instance=None) [source]

log_prob(value) [source]

logits [source]

property param_shape

probs [source]

rsample(sample_shape=torch.Size([])) [source]

support = Real()


arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}


class torch.distributions.relaxed_bernoulli.RelaxedBernoulli(temperature, probs=None, logits=None, validate_args=None) [source]

Bases: torch.distributions.transformed_distribution.TransformedDistribution Creates a RelaxedBernoulli distribution, parametrized by temperature, and either probs or logits (but not both). This is a relaxed version of the Bernoulli distribution, so the values are in (0, 1), and has reparametrizable samples. Example: >>> m = RelaxedBernoulli(torch.tensor([2.2]),
                         torch.tensor([0.1, 0.2, 0.3, 0.99]))
>>> m.sample()
tensor([ 0.2951,  0.3442,  0.8918,  0.9021])
  Parameters

temperature (Tensor) – relaxation temperature
probs (Number, Tensor) – the probability of sampling 1

logits (Number, Tensor) – the log-odds of sampling 1

arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}

expand(batch_shape, _instance=None) [source]

has_rsample = True

property logits

property probs

support = Interval(lower_bound=0.0, upper_bound=1.0)

property temperature


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}


support = Interval(lower_bound=0.0, upper_bound=1.0)


class torch.distributions.relaxed_categorical.RelaxedOneHotCategorical(temperature, probs=None, logits=None, validate_args=None) [source]

Bases: torch.distributions.transformed_distribution.TransformedDistribution Creates a RelaxedOneHotCategorical distribution parametrized by temperature, and either probs or logits. This is a relaxed version of the OneHotCategorical distribution, so its samples are on simplex, and are reparametrizable. Example: >>> m = RelaxedOneHotCategorical(torch.tensor([2.2]),
                                 torch.tensor([0.1, 0.2, 0.3, 0.4]))
>>> m.sample()
tensor([ 0.1294,  0.2324,  0.3859,  0.2523])
  Parameters

temperature (Tensor) – relaxation temperature
probs (Tensor) – event probabilities
logits (Tensor) – unnormalized log probability for each event
arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}

expand(batch_shape, _instance=None) [source]

has_rsample = True

property logits

property probs

support = Simplex()

property temperature


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}


class torch.distributions.studentT.StudentT(df, loc=0.0, scale=1.0, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Creates a Student’s t-distribution parameterized by degree of freedom df, mean loc and scale scale. Example: >>> m = StudentT(torch.tensor([2.0]))
>>> m.sample()  # Student's t-distributed with degrees of freedom=2
tensor([ 0.1046])
  Parameters

df (float or Tensor) – degrees of freedom
loc (float or Tensor) – mean of the distribution
scale (float or Tensor) – scale of the distribution
arg_constraints = {'df': GreaterThan(lower_bound=0.0), 'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

entropy() [source]

expand(batch_shape, _instance=None) [source]

has_rsample = True

log_prob(value) [source]

property mean

rsample(sample_shape=torch.Size([])) [source]

support = Real()

property variance


arg_constraints = {'df': GreaterThan(lower_bound=0.0), 'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}


class torch.distributions.transformed_distribution.TransformedDistribution(base_distribution, transforms, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Extension of the Distribution class, which applies a sequence of Transforms to a base distribution. Let f be the composition of transforms applied: X ~ BaseDistribution
Y = f(X) ~ TransformedDistribution(BaseDistribution, f)
log p(Y) = log p(X) + log |det (dX/dY)|
 Note that the .event_shape of a TransformedDistribution is the maximum shape of its base distribution and its transforms, since transforms can introduce correlations among events. An example for the usage of TransformedDistribution would be: # Building a Logistic Distribution
# X ~ Uniform(0, 1)
# f = a + b * logit(X)
# Y ~ f(X) ~ Logistic(a, b)
base_distribution = Uniform(0, 1)
transforms = [SigmoidTransform().inv, AffineTransform(loc=a, scale=b)]
logistic = TransformedDistribution(base_distribution, transforms)
 For more examples, please look at the implementations of Gumbel, HalfCauchy, HalfNormal, LogNormal, Pareto, Weibull, RelaxedBernoulli and RelaxedOneHotCategorical
arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {}

cdf(value) [source]

Computes the cumulative distribution function by inverting the transform(s) and computing the score of the base distribution.

expand(batch_shape, _instance=None) [source]

property has_rsample

icdf(value) [source]

Computes the inverse cumulative distribution function using transform(s) and computing the score of the base distribution.

log_prob(value) [source]

Scores the sample by inverting the transform(s) and computing the score using the score of the base distribution and the log abs det jacobian.

rsample(sample_shape=torch.Size([])) [source]

Generates a sample_shape shaped reparameterized sample or sample_shape shaped batch of reparameterized samples if the distribution parameters are batched. Samples first from base distribution and applies transform() for every transform in the list.

sample(sample_shape=torch.Size([])) [source]

Generates a sample_shape shaped sample or sample_shape shaped batch of samples if the distribution parameters are batched. Samples first from base distribution and applies transform() for every transform in the list.

property support


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {}


cdf(value) [source]

Computes the cumulative distribution function by inverting the transform(s) and computing the score of the base distribution.


icdf(value) [source]

Computes the inverse cumulative distribution function using transform(s) and computing the score of the base distribution.


log_prob(value) [source]

Scores the sample by inverting the transform(s) and computing the score using the score of the base distribution and the log abs det jacobian.


rsample(sample_shape=torch.Size([])) [source]

Generates a sample_shape shaped reparameterized sample or sample_shape shaped batch of reparameterized samples if the distribution parameters are batched. Samples first from base distribution and applies transform() for every transform in the list.


sample(sample_shape=torch.Size([])) [source]

Generates a sample_shape shaped sample or sample_shape shaped batch of samples if the distribution parameters are batched. Samples first from base distribution and applies transform() for every transform in the list.


class torch.distributions.transforms.AbsTransform(cache_size=0) [source]

Transform via the mapping y=∣x∣y = |x| .


class torch.distributions.transforms.AffineTransform(loc, scale, event_dim=0, cache_size=0) [source]

Transform via the pointwise affine mapping y=loc+scale×xy = \text{loc} + \text{scale} \times x .  Parameters

loc (Tensor or float) – Location parameter.
scale (Tensor or float) – Scale parameter.
event_dim (int) – Optional size of event_shape. This should be zero for univariate random variables, 1 for distributions over vectors, 2 for distributions over matrices, etc.


class torch.distributions.transforms.ComposeTransform(parts, cache_size=0) [source]

Composes multiple transforms in a chain. The transforms being composed are responsible for caching.  Parameters

parts (list of Transform) – A list of transforms to compose.
cache_size (int) – Size of cache. If zero, no caching is done. If one, the latest single value is cached. Only 0 and 1 are supported.


class torch.distributions.transforms.CorrCholeskyTransform(cache_size=0) [source]

Transforms an uncontrained real vector xx  with length D∗(D−1)/2D*(D-1)/2  into the Cholesky factor of a D-dimension correlation matrix. This Cholesky factor is a lower triangular matrix with positive diagonals and unit Euclidean norm for each row. The transform is processed as follows:  First we convert x into a lower triangular matrix in row order. For each row XiX_i  of the lower triangular part, we apply a signed version of class StickBreakingTransform to transform XiX_i  into a unit Euclidean length vector using the following steps: - Scales into the interval (−1,1)(-1, 1)  domain: ri=tanh(Xi)r_i = \tanh(X_i) . - Transforms into an unsigned domain: zi=ri2z_i = r_i^2 . - Applies si=StickBreakingTransform(zi)s_i = StickBreakingTransform(z_i) . - Transforms back into signed domain: yi=sign(ri)∗siy_i = sign(r_i) * \sqrt{s_i} .


class torch.distributions.transforms.ExpTransform(cache_size=0) [source]

Transform via the mapping y=exp(x)y = \exp(x) .


class torch.distributions.transforms.IndependentTransform(base_transform, reinterpreted_batch_ndims, cache_size=0) [source]

Wrapper around another transform to treat reinterpreted_batch_ndims-many extra of the right most dimensions as dependent. This has no effect on the forward or backward transforms, but does sum out reinterpreted_batch_ndims-many of the rightmost dimensions in log_abs_det_jacobian().  Parameters

base_transform (Transform) – A base transform.
reinterpreted_batch_ndims (int) – The number of extra rightmost dimensions to treat as dependent.


class torch.distributions.transforms.LowerCholeskyTransform(cache_size=0) [source]

Transform from unconstrained matrices to lower-triangular matrices with nonnegative diagonal entries. This is useful for parameterizing positive definite matrices in terms of their Cholesky factorization.


class torch.distributions.transforms.PowerTransform(exponent, cache_size=0) [source]

Transform via the mapping y=xexponenty = x^{\text{exponent}} .


class torch.distributions.transforms.ReshapeTransform(in_shape, out_shape, cache_size=0) [source]

Unit Jacobian transform to reshape the rightmost part of a tensor. Note that in_shape and out_shape must have the same number of elements, just as for torch.Tensor.reshape().  Parameters

in_shape (torch.Size) – The input event shape.
out_shape (torch.Size) – The output event shape.


class torch.distributions.transforms.SigmoidTransform(cache_size=0) [source]

Transform via the mapping y=11+exp(−x)y = \frac{1}{1 + \exp(-x)}  and x=logit(y)x = \text{logit}(y) .


class torch.distributions.transforms.SoftmaxTransform(cache_size=0) [source]

Transform from unconstrained space to the simplex via y=exp(x)y = \exp(x)  then normalizing. This is not bijective and cannot be used for HMC. However this acts mostly coordinate-wise (except for the final normalization), and thus is appropriate for coordinate-wise optimization algorithms.


class torch.distributions.transforms.StackTransform(tseq, dim=0, cache_size=0) [source]

Transform functor that applies a sequence of transforms tseq component-wise to each submatrix at dim in a way compatible with torch.stack().  Example::

x = torch.stack([torch.range(1, 10), torch.range(1, 10)], dim=1) t = StackTransform([ExpTransform(), identity_transform], dim=1) y = t(x)


class torch.distributions.transforms.StickBreakingTransform(cache_size=0) [source]

Transform from unconstrained space to the simplex of one additional dimension via a stick-breaking process. This transform arises as an iterated sigmoid transform in a stick-breaking construction of the Dirichlet distribution: the first logit is transformed via sigmoid to the first probability and the probability of everything else, and then the process recurses. This is bijective and appropriate for use in HMC; however it mixes coordinates together and is less appropriate for optimization.


class torch.distributions.transforms.TanhTransform(cache_size=0) [source]

Transform via the mapping y=tanh(x)y = \tanh(x) . It is equivalent to `
ComposeTransform([AffineTransform(0., 2.), SigmoidTransform(), AffineTransform(-1., 2.)])
` However this might not be numerically stable, thus it is recommended to use TanhTransform instead. Note that one should use cache_size=1 when it comes to NaN/Inf values.


class torch.distributions.transforms.Transform(cache_size=0) [source]

Abstract class for invertable transformations with computable log det jacobians. They are primarily used in torch.distributions.TransformedDistribution. Caching is useful for transforms whose inverses are either expensive or numerically unstable. Note that care must be taken with memoized values since the autograd graph may be reversed. For example while the following works with or without caching: y = t(x)
t.log_abs_det_jacobian(x, y).backward()  # x will receive gradients.
 However the following will error when caching due to dependency reversal: y = t(x)
z = t.inv(y)
grad(z.sum(), [y])  # error because z is x
 Derived classes should implement one or both of _call() or _inverse(). Derived classes that set bijective=True should also implement log_abs_det_jacobian().  Parameters
cache_size (int) – Size of cache. If zero, no caching is done. If one, the latest single value is cached. Only 0 and 1 are supported.  Variables

~Transform.domain (Constraint) – The constraint representing valid inputs to this transform.
~Transform.codomain (Constraint) – The constraint representing valid outputs to this transform which are inputs to the inverse transform.
~Transform.bijective (bool) – Whether this transform is bijective. A transform t is bijective iff t.inv(t(x)) == x and t(t.inv(y)) == y for every x in the domain and y in the codomain. Transforms that are not bijective should at least maintain the weaker pseudoinverse properties t(t.inv(t(x)) == t(x) and t.inv(t(t.inv(y))) == t.inv(y).
~Transform.sign (int or Tensor) – For bijective univariate transforms, this should be +1 or -1 depending on whether transform is monotone increasing or decreasing.
property inv
Returns the inverse Transform of this transform. This should satisfy t.inv.inv is t.

property sign
Returns the sign of the determinant of the Jacobian, if applicable. In general this only makes sense for bijective transforms.

log_abs_det_jacobian(x, y) [source]

Computes the log det jacobian log |dy/dx| given input and output.

forward_shape(shape) [source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape) [source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.


forward_shape(shape) [source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.


property inv
Returns the inverse Transform of this transform. This should satisfy t.inv.inv is t.


inverse_shape(shape) [source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.


log_abs_det_jacobian(x, y) [source]

Computes the log det jacobian log |dy/dx| given input and output.


property sign
Returns the sign of the determinant of the Jacobian, if applicable. In general this only makes sense for bijective transforms.


class torch.distributions.uniform.Uniform(low, high, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution Generates uniformly distributed random samples from the half-open interval [low, high). Example: >>> m = Uniform(torch.tensor([0.0]), torch.tensor([5.0]))
>>> m.sample()  # uniformly distributed in the range [0.0, 5.0)
tensor([ 2.3418])
  Parameters

low (float or Tensor) – lower range (inclusive).
high (float or Tensor) – upper range (exclusive).
arg_constraints = {'high': Dependent(), 'low': Dependent()}

cdf(value) [source]

entropy() [source]

expand(batch_shape, _instance=None) [source]

has_rsample = True

icdf(value) [source]

log_prob(value) [source]

property mean

rsample(sample_shape=torch.Size([])) [source]

property stddev

property support

property variance


arg_constraints = {'high': Dependent(), 'low': Dependent()}


class torch.distributions.von_mises.VonMises(loc, concentration, validate_args=None) [source]

Bases: torch.distributions.distribution.Distribution A circular von Mises distribution. This implementation uses polar coordinates. The loc and value args can be any real number (to facilitate unconstrained optimization), but are interpreted as angles modulo 2 pi.  Example::

>>> m = dist.VonMises(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample() # von Mises distributed with loc=1 and concentration=1
tensor([1.9777])
    Parameters

loc (torch.Tensor) – an angle in radians.
concentration (torch.Tensor) – concentration parameter
arg_constraints = {'concentration': GreaterThan(lower_bound=0.0), 'loc': Real()}

expand(batch_shape) [source]

has_rsample = False

log_prob(value) [source]

property mean
The provided mean is the circular one.

sample(sample_shape=torch.Size([])) [source]

The sampling algorithm for the von Mises distribution is based on the following paper: Best, D. J., and Nicholas I. Fisher. “Efficient simulation of the von Mises distribution.” Applied Statistics (1979): 152-157.

support = Real()

variance [source]

The provided variance is the circular one.


arg_constraints = {'concentration': GreaterThan(lower_bound=0.0), 'loc': Real()}


property mean
The provided mean is the circular one.


sample(sample_shape=torch.Size([])) [source]

The sampling algorithm for the von Mises distribution is based on the following paper: Best, D. J., and Nicholas I. Fisher. “Efficient simulation of the von Mises distribution.” Applied Statistics (1979): 152-157.


variance [source]

The provided variance is the circular one.


class torch.distributions.weibull.Weibull(scale, concentration, validate_args=None) [source]

Bases: torch.distributions.transformed_distribution.TransformedDistribution Samples from a two-parameter Weibull distribution. Example >>> m = Weibull(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Weibull distribution with scale=1, concentration=1
tensor([ 0.4784])
  Parameters

scale (float or Tensor) – Scale parameter of distribution (lambda).
concentration (float or Tensor) – Concentration parameter of distribution (k/shape).
arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'concentration': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}

entropy() [source]

expand(batch_shape, _instance=None) [source]

property mean

support = GreaterThan(lower_bound=0.0)

property variance


arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'concentration': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}


torch.div(input, other, *, rounding_mode=None, out=None) → Tensor
Divides each element of the input input by the corresponding element of other.  outi=inputiotheri\text{out}_i = \frac{\text{input}_i}{\text{other}_i}
 Note By default, this performs a “true” division like Python 3. See the rounding_mode argument for floor division.  Supports broadcasting to a common shape, type promotion, and integer, float, and complex inputs. Always promotes integer types to the default scalar type.  Parameters

input (Tensor) – the dividend
other (Tensor or Number) – the divisor   Keyword Arguments

rounding_mode (str, optional) –
Type of rounding applied to the result:  None - default behavior. Performs no rounding and, if both input and other are integer types, promotes the inputs to the default scalar type. Equivalent to true division in Python (the / operator) and NumPy’s np.true_divide.
"trunc" - rounds the results of the division towards zero. Equivalent to C-style integer division.
"floor" - rounds the results of the division down. Equivalent to floor division in Python (the // operator) and NumPy’s np.floor_divide.
out (Tensor, optional) – the output tensor.    Examples: >>> x = torch.tensor([ 0.3810,  1.2774, -0.2972, -0.3719,  0.4637])
>>> torch.div(x, 0.5)
tensor([ 0.7620,  2.5548, -0.5944, -0.7438,  0.9274])

>>> a = torch.tensor([[-0.3711, -1.9353, -0.4605, -0.2917],
...                   [ 0.1815, -1.0111,  0.9805, -1.5923],
...                   [ 0.1062,  1.4581,  0.7759, -1.2344],
...                   [-0.1830, -0.0313,  1.1908, -1.4757]])
>>> b = torch.tensor([ 0.8032,  0.2930, -0.8113, -0.2308])
>>> torch.div(a, b)
tensor([[-0.4620, -6.6051,  0.5676,  1.2639],
        [ 0.2260, -3.4509, -1.2086,  6.8990],
        [ 0.1322,  4.9764, -0.9564,  5.3484],
        [-0.2278, -0.1068, -1.4678,  6.3938]])

>>> torch.div(a, b, rounding_mode='trunc')
tensor([[-0., -6.,  0.,  1.],
        [ 0., -3., -1.,  6.],
        [ 0.,  4., -0.,  5.],
        [-0., -0., -1.,  6.]])

>>> torch.div(a, b, rounding_mode='floor')
tensor([[-1., -7.,  0.,  1.],
        [ 0., -4., -2.,  6.],
        [ 0.,  4., -1.,  5.],
        [-1., -1., -2.,  6.]])


torch.divide(input, other, *, rounding_mode=None, out=None) → Tensor
Alias for torch.div().


torch.dot(input, other, *, out=None) → Tensor
Computes the dot product of two 1D tensors.  Note Unlike NumPy’s dot, torch.dot intentionally only supports computing the dot product of two 1D tensors with the same number of elements.   Parameters

input (Tensor) – first tensor in the dot product, must be 1D.
other (Tensor) – second tensor in the dot product, must be 1D.   Keyword Arguments
{out} –    Example: >>> torch.dot(torch.tensor([2, 3]), torch.tensor([2, 1]))
tensor(7)


torch.dstack(tensors, *, out=None) → Tensor
Stack tensors in sequence depthwise (along third axis). This is equivalent to concatenation along the third axis after 1-D and 2-D tensors have been reshaped by torch.atleast_3d().  Parameters
tensors (sequence of Tensors) – sequence of tensors to concatenate  Keyword Arguments
out (Tensor, optional) – the output tensor.    Example::

>>> a = torch.tensor([1, 2, 3])
>>> b = torch.tensor([4, 5, 6])
>>> torch.dstack((a,b))
tensor([[[1, 4],
         [2, 5],
         [3, 6]]])
>>> a = torch.tensor([[1],[2],[3]])
>>> b = torch.tensor([[4],[5],[6]])
>>> torch.dstack((a,b))
tensor([[[1, 4]],
        [[2, 5]],
        [[3, 6]]])


torch.eig(input, eigenvectors=False, *, out=None) -> (Tensor, Tensor)
Computes the eigenvalues and eigenvectors of a real square matrix.  Note Since eigenvalues and eigenvectors might be complex, backward pass is supported only if eigenvalues and eigenvectors are all real valued. When input is on CUDA, torch.eig() causes host-device synchronization.   Parameters

input (Tensor) – the square matrix of shape (n×n)(n \times n)  for which the eigenvalues and eigenvectors will be computed
eigenvectors (bool) – True to compute both eigenvalues and eigenvectors; otherwise, only eigenvalues will be computed   Keyword Arguments
out (tuple, optional) – the output tensors  Returns
A namedtuple (eigenvalues, eigenvectors) containing
eigenvalues (Tensor): Shape (n×2)(n \times 2) . Each row is an eigenvalue of input, where the first element is the real part and the second element is the imaginary part. The eigenvalues are not necessarily ordered.
eigenvectors (Tensor): If eigenvectors=False, it’s an empty tensor. Otherwise, this tensor of shape (n×n)(n \times n)  can be used to compute normalized (unit length) eigenvectors of corresponding eigenvalues as follows. If the corresponding eigenvalues[j] is a real number, column eigenvectors[:, j] is the eigenvector corresponding to eigenvalues[j]. If the corresponding eigenvalues[j] and eigenvalues[j + 1] form a complex conjugate pair, then the true eigenvectors can be computed as true eigenvector[j]=eigenvectors[:,j]+i×eigenvectors[:,j+1]\text{true eigenvector}[j] = eigenvectors[:, j] + i \times eigenvectors[:, j + 1] , true eigenvector[j+1]=eigenvectors[:,j]−i×eigenvectors[:,j+1]\text{true eigenvector}[j + 1] = eigenvectors[:, j] - i \times eigenvectors[:, j + 1] .   Return type
(Tensor, Tensor)   Example: Trivial example with a diagonal matrix. By default, only eigenvalues are computed:

>>> a = torch.diag(torch.tensor([1, 2, 3], dtype=torch.double))
>>> e, v = torch.eig(a)
>>> e
tensor([[1., 0.],
        [2., 0.],
        [3., 0.]], dtype=torch.float64)
>>> v
tensor([], dtype=torch.float64)

Compute also the eigenvectors:

>>> e, v = torch.eig(a, eigenvectors=True)
>>> e
tensor([[1., 0.],
        [2., 0.],
        [3., 0.]], dtype=torch.float64)
>>> v
tensor([[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.]], dtype=torch.float64)


torch.einsum(equation, *operands) → Tensor [source]

Sums the product of the elements of the input operands along dimensions specified using a notation based on the Einstein summation convention. Einsum allows computing many common multi-dimensional linear algebraic array operations by representing them in a short-hand format based on the Einstein summation convention, given by equation. The details of this format are described below, but the general idea is to label every dimension of the input operands with some subscript and define which subscripts are part of the output. The output is then computed by summing the product of the elements of the operands along the dimensions whose subscripts are not part of the output. For example, matrix multiplication can be computed using einsum as torch.einsum(“ij,jk->ik”, A, B). Here, j is the summation subscript and i and k the output subscripts (see section below for more details on why). Equation: The equation string specifies the subscripts (lower case letters [‘a’, ‘z’]) for each dimension of the input operands in the same order as the dimensions, separating subcripts for each operand by a comma (‘,’), e.g. ‘ij,jk’ specify subscripts for two 2D operands. The dimensions labeled with the same subscript must be broadcastable, that is, their size must either match or be 1. The exception is if a subscript is repeated for the same input operand, in which case the dimensions labeled with this subscript for this operand must match in size and the operand will be replaced by its diagonal along these dimensions. The subscripts that appear exactly once in the equation will be part of the output, sorted in increasing alphabetical order. The output is computed by multiplying the input operands element-wise, with their dimensions aligned based on the subscripts, and then summing out the dimensions whose subscripts are not part of the output. Optionally, the output subscripts can be explicitly defined by adding an arrow (‘->’) at the end of the equation followed by the subscripts for the output. For instance, the following equation computes the transpose of a matrix multiplication: ‘ij,jk->ki’. The output subscripts must appear at least once for some input operand and at most once for the output. Ellipsis (‘…’) can be used in place of subscripts to broadcast the dimensions covered by the ellipsis. Each input operand may contain at most one ellipsis which will cover the dimensions not covered by subscripts, e.g. for an input operand with 5 dimensions, the ellipsis in the equation ‘ab…c’ cover the third and fourth dimensions. The ellipsis does not need to cover the same number of dimensions across the operands but the ‘shape’ of the ellipsis (the size of the dimensions covered by them) must broadcast together. If the output is not explicitly defined with the arrow (‘->’) notation, the ellipsis will come first in the output (left-most dimensions), before the subscript labels that appear exactly once for the input operands. e.g. the following equation implements batch matrix multiplication ‘…ij,…jk’. A few final notes: the equation may contain whitespaces between the different elements (subscripts, ellipsis, arrow and comma) but something like ‘…’ is not valid. An empty string ‘’ is valid for scalar operands.  Note torch.einsum handles ellipsis (‘…’) differently from NumPy in that it allows dimensions covered by the ellipsis to be summed over, that is, ellipsis are not required to be part of the output.   Note This function does not optimize the given expression, so a different formula for the same computation may run faster or consume less memory. Projects like opt_einsum (https://optimized-einsum.readthedocs.io/en/stable/) can optimize the formula for you.   Parameters

equation (string) – The subscripts for the Einstein summation.
operands (Tensor) – The operands to compute the Einstein sum of.    Examples: # trace
>>> torch.einsum('ii', torch.randn(4, 4))
tensor(-1.2104)

# diagonal
>>> torch.einsum('ii->i', torch.randn(4, 4))
tensor([-0.1034,  0.7952, -0.2433,  0.4545])

# outer product
>>> x = torch.randn(5)
>>> y = torch.randn(4)
>>> torch.einsum('i,j->ij', x, y)
tensor([[ 0.1156, -0.2897, -0.3918,  0.4963],
        [-0.3744,  0.9381,  1.2685, -1.6070],
        [ 0.7208, -1.8058, -2.4419,  3.0936],
        [ 0.1713, -0.4291, -0.5802,  0.7350],
        [ 0.5704, -1.4290, -1.9323,  2.4480]])

# batch matrix multiplication
>>> As = torch.randn(3,2,5)
>>> Bs = torch.randn(3,5,4)
>>> torch.einsum('bij,bjk->bik', As, Bs)
tensor([[[-1.0564, -1.5904,  3.2023,  3.1271],
        [-1.6706, -0.8097, -0.8025, -2.1183]],

        [[ 4.2239,  0.3107, -0.5756, -0.2354],
        [-1.4558, -0.3460,  1.5087, -0.8530]],

        [[ 2.8153,  1.8787, -4.3839, -1.2112],
        [ 0.3728, -2.1131,  0.0921,  0.8305]]])

# batch permute
>>> A = torch.randn(2, 3, 4, 5)
>>> torch.einsum('...ij->...ji', A).shape
torch.Size([2, 3, 5, 4])

# equivalent to torch.nn.functional.bilinear
>>> A = torch.randn(3,5,4)
>>> l = torch.randn(2,5)
>>> r = torch.randn(2,4)
>>> torch.einsum('bn,anm,bm->ba', l, A, r)
tensor([[-0.3430, -5.2405,  0.4494],
        [ 0.3311,  5.5201, -3.0356]])


torch.empty(*size, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False, pin_memory=False) → Tensor
Returns a tensor filled with uninitialized data. The shape of the tensor is defined by the variable argument size.  Parameters
size (int...) – a sequence of integers defining the shape of the output tensor. Can be a variable number of arguments or a collection like a list or tuple.  Keyword Arguments

out (Tensor, optional) – the output tensor.
dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_tensor_type()).
layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.
pin_memory (bool, optional) – If set, returned tensor would be allocated in the pinned memory. Works only for CPU tensors. Default: False.
memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.contiguous_format.    Example: >>> torch.empty(2, 3)
tensor(1.00000e-08 *
       [[ 6.3984,  0.0000,  0.0000],
        [ 0.0000,  0.0000,  0.0000]])


torch.empty_like(input, *, dtype=None, layout=None, device=None, requires_grad=False, memory_format=torch.preserve_format) → Tensor
Returns an uninitialized tensor with the same size as input. torch.empty_like(input) is equivalent to torch.empty(input.size(), dtype=input.dtype, layout=input.layout, device=input.device).  Parameters
input (Tensor) – the size of input will determine size of the output tensor.  Keyword Arguments

dtype (torch.dtype, optional) – the desired data type of returned Tensor. Default: if None, defaults to the dtype of input.
layout (torch.layout, optional) – the desired layout of returned tensor. Default: if None, defaults to the layout of input.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, defaults to the device of input.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.
memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.preserve_format.    Example: >>> torch.empty((2,3), dtype=torch.int64)
tensor([[ 9.4064e+13,  2.8000e+01,  9.3493e+13],
        [ 7.5751e+18,  7.1428e+18,  7.5955e+18]])


torch.empty_strided(size, stride, *, dtype=None, layout=None, device=None, requires_grad=False, pin_memory=False) → Tensor
Returns a tensor filled with uninitialized data. The shape and strides of the tensor is defined by the variable argument size and stride respectively. torch.empty_strided(size, stride) is equivalent to torch.empty(size).as_strided(size, stride).  Warning More than one element of the created tensor may refer to a single memory location. As a result, in-place operations (especially ones that are vectorized) may result in incorrect behavior. If you need to write to the tensors, please clone them first.   Parameters

size (tuple of python:ints) – the shape of the output tensor
stride (tuple of python:ints) – the strides of the output tensor   Keyword Arguments

dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_tensor_type()).
layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.
pin_memory (bool, optional) – If set, returned tensor would be allocated in the pinned memory. Works only for CPU tensors. Default: False.    Example: >>> a = torch.empty_strided((2, 3), (1, 2))
>>> a
tensor([[8.9683e-44, 4.4842e-44, 5.1239e+07],
        [0.0000e+00, 0.0000e+00, 3.0705e-41]])
>>> a.stride()
(1, 2)
>>> a.size()
torch.Size([2, 3])


class torch.enable_grad [source]

Context-manager that enables gradient calculation. Enables gradient calculation, if it has been disabled via no_grad or set_grad_enabled. This context manager is thread local; it will not affect computation in other threads. Also functions as a decorator. (Make sure to instantiate with parenthesis.) Example: >>> x = torch.tensor([1], requires_grad=True)
>>> with torch.no_grad():
...   with torch.enable_grad():
...     y = x * 2
>>> y.requires_grad
True
>>> y.backward()
>>> x.grad
>>> @torch.enable_grad()
... def doubler(x):
...     return x * 2
>>> with torch.no_grad():
...     z = doubler(x)
>>> z.requires_grad
True


torch.eq(input, other, *, out=None) → Tensor
Computes element-wise equality The second argument can be a number or a tensor whose shape is broadcastable with the first argument.  Parameters

input (Tensor) – the tensor to compare
other (Tensor or float) – the tensor or value to compare   Keyword Arguments
out (Tensor, optional) – the output tensor.  Returns
A boolean tensor that is True where input is equal to other and False elsewhere   Example: >>> torch.eq(torch.tensor([[1, 2], [3, 4]]), torch.tensor([[1, 1], [4, 4]]))
tensor([[ True, False],
        [False, True]])


torch.equal(input, other) → bool
True if two tensors have the same size and elements, False otherwise. Example: >>> torch.equal(torch.tensor([1, 2]), torch.tensor([1, 2]))
True


torch.erf(input, *, out=None) → Tensor
Computes the error function of each element. The error function is defined as follows:  erf(x)=2π∫0xe−t2dt\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.erf(torch.tensor([0, -1., 10.]))
tensor([ 0.0000, -0.8427,  1.0000])


torch.erfc(input, *, out=None) → Tensor
Computes the complementary error function of each element of input. The complementary error function is defined as follows:  erfc(x)=1−2π∫0xe−t2dt\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.erfc(torch.tensor([0, -1., 10.]))
tensor([ 1.0000, 1.8427,  0.0000])


torch.erfinv(input, *, out=None) → Tensor
Computes the inverse error function of each element of input. The inverse error function is defined in the range (−1,1)(-1, 1)  as:  erfinv(erf(x))=x\mathrm{erfinv}(\mathrm{erf}(x)) = x
 Parameters
input (Tensor) – the input tensor.  Keyword Arguments
out (Tensor, optional) – the output tensor.   Example: >>> torch.erfinv(torch.tensor([0, 0.5, -1.]))
tensor([ 0.0000,  0.4769,    -inf])


torch.exp(input, *, out=None) → Tensor
Returns a new tensor with the exponential of the elements of the input tensor input.  yi=exiy_{i} = e^{x_{i}}
 Parameters
input (Tensor) – the input tensor.  Keyword Arguments
out (Tensor, optional) – the output tensor.   Example: >>> torch.exp(torch.tensor([0, math.log(2.)]))
tensor([ 1.,  2.])


torch.exp2(input, *, out=None) → Tensor
Computes the base two exponential function of input.  yi=2xiy_{i} = 2^{x_{i}}
 Parameters
input (Tensor) – the input tensor.  Keyword Arguments
out (Tensor, optional) – the output tensor.   Example: >>> torch.exp2(torch.tensor([0, math.log2(2.), 3, 4]))
tensor([ 1.,  2.,  8., 16.])


torch.expm1(input, *, out=None) → Tensor
Returns a new tensor with the exponential of the elements minus 1 of input.  yi=exi−1y_{i} = e^{x_{i}} - 1
 Parameters
input (Tensor) – the input tensor.  Keyword Arguments
out (Tensor, optional) – the output tensor.   Example: >>> torch.expm1(torch.tensor([0, math.log(2.)]))
tensor([ 0.,  1.])


torch.eye(n, m=None, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False) → Tensor
Returns a 2-D tensor with ones on the diagonal and zeros elsewhere.  Parameters

n (int) – the number of rows
m (int, optional) – the number of columns with default being n
   Keyword Arguments

out (Tensor, optional) – the output tensor.
dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_tensor_type()).
layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.   Returns
A 2-D tensor with ones on the diagonal and zeros elsewhere  Return type
Tensor   Example: >>> torch.eye(3)
tensor([[ 1.,  0.,  0.],
        [ 0.,  1.,  0.],
        [ 0.,  0.,  1.]])


torch.fake_quantize_per_channel_affine(input, scale, zero_point, quant_min, quant_max) → Tensor
Returns a new tensor with the data in input fake quantized per channel using scale, zero_point, quant_min and quant_max, across the channel specified by axis.  output=min(quant_max,max(quant_min,std::nearby_int(input/scale)+zero_point))\text{output} = min( \text{quant\_max}, max( \text{quant\_min}, \text{std::nearby\_int}(\text{input} / \text{scale}) + \text{zero\_point} ) )
 Parameters

input (Tensor) – the input value(s), in torch.float32.
scale (Tensor) – quantization scale, per channel
zero_point (Tensor) – quantization zero_point, per channel
axis (int32) – channel axis
quant_min (int64) – lower bound of the quantized domain
quant_max (int64) – upper bound of the quantized domain   Returns
A newly fake_quantized per channel tensor  Return type
Tensor   Example: >>> x = torch.randn(2, 2, 2)
>>> x
tensor([[[-0.2525, -0.0466],
         [ 0.3491, -0.2168]],

        [[-0.5906,  1.6258],
         [ 0.6444, -0.0542]]])
>>> scales = (torch.randn(2) + 1) * 0.05
>>> scales
tensor([0.0475, 0.0486])
>>> zero_points = torch.zeros(2).to(torch.long)
>>> zero_points
tensor([0, 0])
>>> torch.fake_quantize_per_channel_affine(x, scales, zero_points, 1, 0, 255)
tensor([[[0.0000, 0.0000],
         [0.3405, 0.0000]],

        [[0.0000, 1.6134],
        [0.6323, 0.0000]]])


torch.fake_quantize_per_tensor_affine(input, scale, zero_point, quant_min, quant_max) → Tensor
Returns a new tensor with the data in input fake quantized using scale, zero_point, quant_min and quant_max.  output=min(quant_max,max(quant_min,std::nearby_int(input/scale)+zero_point))\text{output} = min( \text{quant\_max}, max( \text{quant\_min}, \text{std::nearby\_int}(\text{input} / \text{scale}) + \text{zero\_point} ) )
 Parameters

input (Tensor) – the input value(s), in torch.float32.
scale (double) – quantization scale
zero_point (int64) – quantization zero_point
quant_min (int64) – lower bound of the quantized domain
quant_max (int64) – upper bound of the quantized domain   Returns
A newly fake_quantized tensor  Return type
Tensor   Example: >>> x = torch.randn(4)
>>> x
tensor([ 0.0552,  0.9730,  0.3973, -1.0780])
>>> torch.fake_quantize_per_tensor_affine(x, 0.1, 0, 0, 255)
tensor([0.1000, 1.0000, 0.4000, 0.0000])


torch.fft Discrete Fourier transforms and related functions. Fast Fourier Transforms
torch.fft.fft(input, n=None, dim=-1, norm=None) → Tensor
Computes the one dimensional discrete Fourier transform of input.  Note The Fourier domain representation of any real signal satisfies the Hermitian property: X[i] = conj(X[-i]). This function always returns both the positive and negative frequency terms even though, for real inputs, the negative frequencies are redundant. rfft() returns the more compact one-sided representation where only the positive frequencies are returned.   Parameters

input (Tensor) – the input tensor
n (int, optional) – Signal length. If given, the input will either be zero-padded or trimmed to this length before computing the FFT.
dim (int, optional) – The dimension along which to take the one dimensional FFT.
norm (str, optional) –
Normalization mode. For the forward transform (fft()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Calling the backward transform (ifft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifft() the exact inverse. Default is "backward" (no normalization).     Example >>> t = torch.arange(4)
>>> t
tensor([0, 1, 2, 3])
>>> torch.fft.fft(t)
tensor([ 6.+0.j, -2.+2.j, -2.+0.j, -2.-2.j])
 >>> t = tensor([0.+1.j, 2.+3.j, 4.+5.j, 6.+7.j])
>>> torch.fft.fft(t)
tensor([12.+16.j, -8.+0.j, -4.-4.j,  0.-8.j])

torch.fft.ifft(input, n=None, dim=-1, norm=None) → Tensor
Computes the one dimensional inverse discrete Fourier transform of input.  Parameters

input (Tensor) – the input tensor
n (int, optional) – Signal length. If given, the input will either be zero-padded or trimmed to this length before computing the IFFT.
dim (int, optional) – The dimension along which to take the one dimensional IFFT.
norm (str, optional) –
Normalization mode. For the backward transform (ifft()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the IFFT orthonormal)  Calling the forward transform (fft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifft() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> t = torch.tensor([ 6.+0.j, -2.+2.j, -2.+0.j, -2.-2.j])
>>> torch.fft.ifft(t)
tensor([0.+0.j, 1.+0.j, 2.+0.j, 3.+0.j])

torch.fft.fft2(input, s=None, dim=(-2, -1), norm=None) → Tensor
Computes the 2 dimensional discrete Fourier transform of input. Equivalent to fftn() but FFTs only the last two dimensions by default.  Note The Fourier domain representation of any real signal satisfies the Hermitian property: X[i, j] = conj(X[-i, -j]). This function always returns all positive and negative frequency terms even though, for real inputs, half of these values are redundant. rfft2() returns the more compact one-sided representation where only the positive frequencies of the last dimension are returned.   Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the FFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: last two dimensions.
norm (str, optional) –
Normalization mode. For the forward transform (fft2()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Where n = prod(s) is the logical FFT size. Calling the backward transform (ifft2()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifft2() the exact inverse. Default is "backward" (no normalization).     Example >>> x = torch.rand(10, 10, dtype=torch.complex64)
>>> fft2 = torch.fft.fft2(t)
 The discrete Fourier transform is separable, so fft2() here is equivalent to two one-dimensional fft() calls: >>> two_ffts = torch.fft.fft(torch.fft.fft(x, dim=0), dim=1)
>>> torch.allclose(fft2, two_ffts)

torch.fft.ifft2(input, s=None, dim=(-2, -1), norm=None) → Tensor
Computes the 2 dimensional inverse discrete Fourier transform of input. Equivalent to ifftn() but IFFTs only the last two dimensions by default.  Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the IFFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: last two dimensions.
norm (str, optional) –
Normalization mode. For the backward transform (ifft2()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the IFFT orthonormal)  Where n = prod(s) is the logical IFFT size. Calling the forward transform (fft2()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifft2() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> x = torch.rand(10, 10, dtype=torch.complex64)
>>> ifft2 = torch.fft.ifft2(t)
 The discrete Fourier transform is separable, so ifft2() here is equivalent to two one-dimensional ifft() calls: >>> two_iffts = torch.fft.ifft(torch.fft.ifft(x, dim=0), dim=1)
>>> torch.allclose(ifft2, two_iffts)

torch.fft.fftn(input, s=None, dim=None, norm=None) → Tensor
Computes the N dimensional discrete Fourier transform of input.  Note The Fourier domain representation of any real signal satisfies the Hermitian property: X[i_1, ..., i_n] = conj(X[-i_1, ..., -i_n]). This function always returns all positive and negative frequency terms even though, for real inputs, half of these values are redundant. rfftn() returns the more compact one-sided representation where only the positive frequencies of the last dimension are returned.   Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the FFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: all dimensions, or the last len(s) dimensions if s is given.
norm (str, optional) –
Normalization mode. For the forward transform (fftn()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Where n = prod(s) is the logical FFT size. Calling the backward transform (ifftn()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifftn() the exact inverse. Default is "backward" (no normalization).     Example >>> x = torch.rand(10, 10, dtype=torch.complex64)
>>> fftn = torch.fft.fftn(t)
 The discrete Fourier transform is separable, so fftn() here is equivalent to two one-dimensional fft() calls: >>> two_ffts = torch.fft.fft(torch.fft.fft(x, dim=0), dim=1)
>>> torch.allclose(fftn, two_ffts)

torch.fft.ifftn(input, s=None, dim=None, norm=None) → Tensor
Computes the N dimensional inverse discrete Fourier transform of input.  Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the IFFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: all dimensions, or the last len(s) dimensions if s is given.
norm (str, optional) –
Normalization mode. For the backward transform (ifftn()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the IFFT orthonormal)  Where n = prod(s) is the logical IFFT size. Calling the forward transform (fftn()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifftn() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> x = torch.rand(10, 10, dtype=torch.complex64)
>>> ifftn = torch.fft.ifftn(t)
 The discrete Fourier transform is separable, so ifftn() here is equivalent to two one-dimensional ifft() calls: >>> two_iffts = torch.fft.ifft(torch.fft.ifft(x, dim=0), dim=1)
>>> torch.allclose(ifftn, two_iffts)

torch.fft.rfft(input, n=None, dim=-1, norm=None) → Tensor
Computes the one dimensional Fourier transform of real-valued input. The FFT of a real signal is Hermitian-symmetric, X[i] = conj(X[-i]) so the output contains only the positive frequencies below the Nyquist frequency. To compute the full output, use fft()  Parameters

input (Tensor) – the real input tensor
n (int, optional) – Signal length. If given, the input will either be zero-padded or trimmed to this length before computing the real FFT.
dim (int, optional) – The dimension along which to take the one dimensional real FFT.
norm (str, optional) –
Normalization mode. For the forward transform (rfft()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Calling the backward transform (irfft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make irfft() the exact inverse. Default is "backward" (no normalization).     Example >>> t = torch.arange(4)
>>> t
tensor([0, 1, 2, 3])
>>> torch.fft.rfft(t)
tensor([ 6.+0.j, -2.+2.j, -2.+0.j])
 Compare against the full output from fft(): >>> torch.fft.fft(t)
tensor([ 6.+0.j, -2.+2.j, -2.+0.j, -2.-2.j])
 Notice that the symmetric element T[-1] == T[1].conj() is omitted. At the Nyquist frequency T[-2] == T[2] is it’s own symmetric pair, and therefore must always be real-valued.

torch.fft.irfft(input, n=None, dim=-1, norm=None) → Tensor
Computes the inverse of rfft(). input is interpreted as a one-sided Hermitian signal in the Fourier domain, as produced by rfft(). By the Hermitian property, the output will be real-valued.  Note Some input frequencies must be real-valued to satisfy the Hermitian property. In these cases the imaginary component will be ignored. For example, any imaginary component in the zero-frequency term cannot be represented in a real output and so will always be ignored.   Note The correct interpretation of the Hermitian input depends on the length of the original data, as given by n. This is because each input shape could correspond to either an odd or even length signal. By default, the signal is assumed to be even length and odd signals will not round-trip properly. So, it is recommended to always pass the signal length n.   Parameters

input (Tensor) – the input tensor representing a half-Hermitian signal
n (int, optional) – Output signal length. This determines the length of the output signal. If given, the input will either be zero-padded or trimmed to this length before computing the real IFFT. Defaults to even output: n=2*(input.size(dim) - 1).
dim (int, optional) – The dimension along which to take the one dimensional real IFFT.
norm (str, optional) –
Normalization mode. For the backward transform (irfft()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the real IFFT orthonormal)  Calling the forward transform (rfft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make irfft() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> t = torch.arange(5)
>>> t
tensor([0, 1, 2, 3, 4])
>>> T = torch.fft.rfft(t)
>>> T
tensor([10.0000+0.0000j, -2.5000+3.4410j, -2.5000+0.8123j])
 Without specifying the output length to irfft(), the output will not round-trip properly because the input is odd-length: >>> torch.fft.irfft(T)
tensor([0.6250, 1.4045, 3.1250, 4.8455])
 So, it is recommended to always pass the signal length n: >>> torch.fft.irfft(T, t.numel())
tensor([0.0000, 1.0000, 2.0000, 3.0000, 4.0000])

torch.fft.rfft2(input, s=None, dim=(-2, -1), norm=None) → Tensor
Computes the 2-dimensional discrete Fourier transform of real input. Equivalent to rfftn() but FFTs only the last two dimensions by default. The FFT of a real signal is Hermitian-symmetric, X[i, j] = conj(X[-i, -j]), so the full fft2() output contains redundant information. rfft2() instead omits the negative frequencies in the last dimension.  Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the real FFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: last two dimensions.
norm (str, optional) –
Normalization mode. For the forward transform (rfft2()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the real FFT orthonormal)  Where n = prod(s) is the logical FFT size. Calling the backward transform (irfft2()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make irfft2() the exact inverse. Default is "backward" (no normalization).     Example >>> t = torch.rand(10, 10)
>>> rfft2 = torch.fft.rfft2(t)
>>> rfft2.size()
torch.Size([10, 6])
 Compared against the full output from fft2(), we have all elements up to the Nyquist frequency. >>> fft2 = torch.fft.fft2(t)
>>> torch.allclose(fft2[..., :6], rfft2)
True
 The discrete Fourier transform is separable, so rfft2() here is equivalent to a combination of fft() and rfft(): >>> two_ffts = torch.fft.fft(torch.fft.rfft(x, dim=1), dim=0)
>>> torch.allclose(rfft2, two_ffts)

torch.fft.irfft2(input, s=None, dim=(-2, -1), norm=None) → Tensor
Computes the inverse of rfft2(). Equivalent to irfftn() but IFFTs only the last two dimensions by default. input is interpreted as a one-sided Hermitian signal in the Fourier domain, as produced by rfft2(). By the Hermitian property, the output will be real-valued.  Note Some input frequencies must be real-valued to satisfy the Hermitian property. In these cases the imaginary component will be ignored. For example, any imaginary component in the zero-frequency term cannot be represented in a real output and so will always be ignored.   Note The correct interpretation of the Hermitian input depends on the length of the original data, as given by s. This is because each input shape could correspond to either an odd or even length signal. By default, the signal is assumed to be even length and odd signals will not round-trip properly. So, it is recommended to always pass the signal shape s.   Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the real FFT. If a length -1 is specified, no padding is done in that dimension. Defaults to even output in the last dimension: s[-1] = 2*(input.size(dim[-1]) - 1).
dim (Tuple[int], optional) – Dimensions to be transformed. The last dimension must be the half-Hermitian compressed dimension. Default: last two dimensions.
norm (str, optional) –
Normalization mode. For the backward transform (irfft2()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the real IFFT orthonormal)  Where n = prod(s) is the logical IFFT size. Calling the forward transform (rfft2()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make irfft2() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> t = torch.rand(10, 9)
>>> T = torch.fft.rfft2(t)
 Without specifying the output length to irfft2(), the output will not round-trip properly because the input is odd-length in the last dimension: >>> torch.fft.irfft2(T).size()
torch.Size([10, 10])
 So, it is recommended to always pass the signal shape s. >>> roundtrip = torch.fft.irfft2(T, t.size())
>>> roundtrip.size()
torch.Size([10, 9])
>>> torch.allclose(roundtrip, t)
True

torch.fft.rfftn(input, s=None, dim=None, norm=None) → Tensor
Computes the N-dimensional discrete Fourier transform of real input. The FFT of a real signal is Hermitian-symmetric, X[i_1, ..., i_n] = conj(X[-i_1, ..., -i_n]) so the full fftn() output contains redundant information. rfftn() instead omits the negative frequencies in the last dimension.  Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the real FFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: all dimensions, or the last len(s) dimensions if s is given.
norm (str, optional) –
Normalization mode. For the forward transform (rfftn()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the real FFT orthonormal)  Where n = prod(s) is the logical FFT size. Calling the backward transform (irfftn()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make irfftn() the exact inverse. Default is "backward" (no normalization).     Example >>> t = torch.rand(10, 10)
>>> rfftn = torch.fft.rfftn(t)
>>> rfftn.size()
torch.Size([10, 6])
 Compared against the full output from fftn(), we have all elements up to the Nyquist frequency. >>> fftn = torch.fft.fftn(t)
>>> torch.allclose(fftn[..., :6], rfftn)
True
 The discrete Fourier transform is separable, so rfftn() here is equivalent to a combination of fft() and rfft(): >>> two_ffts = torch.fft.fft(torch.fft.rfft(x, dim=1), dim=0)
>>> torch.allclose(rfftn, two_ffts)

torch.fft.irfftn(input, s=None, dim=None, norm=None) → Tensor
Computes the inverse of rfftn(). input is interpreted as a one-sided Hermitian signal in the Fourier domain, as produced by rfftn(). By the Hermitian property, the output will be real-valued.  Note Some input frequencies must be real-valued to satisfy the Hermitian property. In these cases the imaginary component will be ignored. For example, any imaginary component in the zero-frequency term cannot be represented in a real output and so will always be ignored.   Note The correct interpretation of the Hermitian input depends on the length of the original data, as given by s. This is because each input shape could correspond to either an odd or even length signal. By default, the signal is assumed to be even length and odd signals will not round-trip properly. So, it is recommended to always pass the signal shape s.   Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the real FFT. If a length -1 is specified, no padding is done in that dimension. Defaults to even output in the last dimension: s[-1] = 2*(input.size(dim[-1]) - 1).
dim (Tuple[int], optional) – Dimensions to be transformed. The last dimension must be the half-Hermitian compressed dimension. Default: all dimensions, or the last len(s) dimensions if s is given.
norm (str, optional) –
Normalization mode. For the backward transform (irfftn()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the real IFFT orthonormal)  Where n = prod(s) is the logical IFFT size. Calling the forward transform (rfftn()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make irfftn() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> t = torch.rand(10, 9)
>>> T = torch.fft.rfftn(t)
 Without specifying the output length to irfft(), the output will not round-trip properly because the input is odd-length in the last dimension: >>> torch.fft.irfftn(T).size()
torch.Size([10, 10])
 So, it is recommended to always pass the signal shape s. >>> roundtrip = torch.fft.irfftn(T, t.size())
>>> roundtrip.size()
torch.Size([10, 9])
>>> torch.allclose(roundtrip, t)
True

torch.fft.hfft(input, n=None, dim=-1, norm=None) → Tensor
Computes the one dimensional discrete Fourier transform of a Hermitian symmetric input signal.  Note hfft()/ihfft() are analogous to rfft()/irfft(). The real FFT expects a real signal in the time-domain and gives a Hermitian symmetry in the frequency-domain. The Hermitian FFT is the opposite; Hermitian symmetric in the time-domain and real-valued in the frequency-domain. For this reason, special care needs to be taken with the length argument n, in the same way as with irfft().   Note Because the signal is Hermitian in the time-domain, the result will be real in the frequency domain. Note that some input frequencies must be real-valued to satisfy the Hermitian property. In these cases the imaginary component will be ignored. For example, any imaginary component in input[0] would result in one or more complex frequency terms which cannot be represented in a real output and so will always be ignored.   Note The correct interpretation of the Hermitian input depends on the length of the original data, as given by n. This is because each input shape could correspond to either an odd or even length signal. By default, the signal is assumed to be even length and odd signals will not round-trip properly. So, it is recommended to always pass the signal length n.   Parameters

input (Tensor) – the input tensor representing a half-Hermitian signal
n (int, optional) – Output signal length. This determines the length of the real output. If given, the input will either be zero-padded or trimmed to this length before computing the Hermitian FFT. Defaults to even output: n=2*(input.size(dim) - 1).
dim (int, optional) – The dimension along which to take the one dimensional Hermitian FFT.
norm (str, optional) –
Normalization mode. For the forward transform (hfft()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the Hermitian FFT orthonormal)  Calling the backward transform (ihfft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ihfft() the exact inverse. Default is "backward" (no normalization).     Example Taking a real-valued frequency signal and bringing it into the time domain gives Hermitian symmetric output: >>> t = torch.arange(5)
>>> t
tensor([0, 1, 2, 3, 4])
>>> T = torch.fft.ifft(t)
>>> T
tensor([ 2.0000+-0.0000j, -0.5000-0.6882j, -0.5000-0.1625j, -0.5000+0.1625j,
        -0.5000+0.6882j])
 Note that T[1] == T[-1].conj() and T[2] == T[-2].conj() is redundant. We can thus compute the forward transform without considering negative frequencies: >>> torch.fft.hfft(T[:3], n=5)
tensor([0., 1., 2., 3., 4.])
 Like with irfft(), the output length must be given in order to recover an even length output: >>> torch.fft.hfft(T[:3])
tensor([0.5000, 1.1236, 2.5000, 3.8764])

torch.fft.ihfft(input, n=None, dim=-1, norm=None) → Tensor
Computes the inverse of hfft(). input must be a real-valued signal, interpreted in the Fourier domain. The IFFT of a real signal is Hermitian-symmetric, X[i] = conj(X[-i]). ihfft() represents this in the one-sided form where only the positive frequencies below the Nyquist frequency are included. To compute the full output, use ifft().  Parameters

input (Tensor) – the real input tensor
n (int, optional) – Signal length. If given, the input will either be zero-padded or trimmed to this length before computing the Hermitian IFFT.
dim (int, optional) – The dimension along which to take the one dimensional Hermitian IFFT.
norm (str, optional) –
Normalization mode. For the backward transform (ihfft()), these correspond to:
"forward" - no normalization
"backward" - normalize by 1/n

"ortho" - normalize by 1/sqrt(n) (making the IFFT orthonormal)  Calling the forward transform (hfft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ihfft() the exact inverse. Default is "backward" (normalize by 1/n).     Example >>> t = torch.arange(5)
>>> t
tensor([0, 1, 2, 3, 4])
>>> torch.fft.ihfft(t)
tensor([ 2.0000+-0.0000j, -0.5000-0.6882j, -0.5000-0.1625j])
 Compare against the full output from ifft(): >>> torch.fft.ifft(t)
tensor([ 2.0000+-0.0000j, -0.5000-0.6882j, -0.5000-0.1625j, -0.5000+0.1625j,
    -0.5000+0.6882j])

 Helper Functions
torch.fft.fftfreq(n, d=1.0, *, dtype=None, layout=torch.strided, device=None, requires_grad=False) → Tensor
Computes the discrete Fourier Transform sample frequencies for a signal of size n.  Note By convention, fft() returns positive frequency terms first, followed by the negative frequencies in reverse order, so that f[-i] for all 0<i≤n/20 < i \leq n/2  in Python gives the negative frequency terms. For an FFT of length n and with inputs spaced in length unit d, the frequencies are: f = [0, 1, ..., (n - 1) // 2, -(n // 2), ..., -1] / (d * n)
   Note For even lengths, the Nyquist frequency at f[n/2] can be thought of as either negative or positive. fftfreq() follows NumPy’s convention of taking it to be negative.   Parameters

n (int) – the FFT length
d (float, optional) – The sampling length scale. The spacing between individual samples of the FFT input. The default assumes unit spacing, dividing that result by the actual spacing gives the result in physical frequency units.   Keyword Arguments

dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_tensor_type()).
layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.    Example >>> torch.fft.fftfreq(5)
tensor([ 0.0000,  0.2000,  0.4000, -0.4000, -0.2000])
 For even input, we can see the Nyquist frequency at f[2] is given as negative: >>> torch.fft.fftfreq(4)
tensor([ 0.0000,  0.2500, -0.5000, -0.2500])

torch.fft.rfftfreq(n, d=1.0, *, dtype=None, layout=torch.strided, device=None, requires_grad=False) → Tensor
Computes the sample frequencies for rfft() with a signal of size n.  Note rfft() returns Hermitian one-sided output, so only the positive frequency terms are returned. For a real FFT of length n and with inputs spaced in length unit d, the frequencies are: f = torch.arange((n + 1) // 2) / (d * n)
   Note For even lengths, the Nyquist frequency at f[n/2] can be thought of as either negative or positive. Unlike fftfreq(), rfftfreq() always returns it as positive.   Parameters

n (int) – the real FFT length
d (float, optional) – The sampling length scale. The spacing between individual samples of the FFT input. The default assumes unit spacing, dividing that result by the actual spacing gives the result in physical frequency units.   Keyword Arguments

dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_tensor_type()).
layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.    Example >>> torch.fft.rfftfreq(5)
tensor([ 0.0000,  0.2000,  0.4000])
 >>> torch.fft.rfftfreq(4)
tensor([ 0.0000,  0.2500, 0.5000])
 Compared to the output from fftfreq(), we see that the Nyquist frequency at f[2] has changed sign: >>> torch.fft.fftfreq(4) tensor([ 0.0000, 0.2500, -0.5000, -0.2500])

torch.fft.fftshift(input, dim=None) → Tensor
Reorders n-dimensional FFT data, as provided by fftn(), to have negative frequency terms first. This performs a periodic shift of n-dimensional data such that the origin (0, ..., 0) is moved to the center of the tensor. Specifically, to input.shape[dim] // 2 in each selected dimension.  Note By convention, the FFT returns positive frequency terms first, followed by the negative frequencies in reverse order, so that f[-i] for all 0<i≤n/20 < i \leq n/2  in Python gives the negative frequency terms. fftshift() rearranges all frequencies into ascending order from negative to positive with the zero-frequency term in the center.   Note For even lengths, the Nyquist frequency at f[n/2] can be thought of as either negative or positive. fftshift() always puts the Nyquist term at the 0-index. This is the same convention used by fftfreq().   Parameters

input (Tensor) – the tensor in FFT order
dim (int, Tuple[int], optional) – The dimensions to rearrange. Only dimensions specified here will be rearranged, any other dimensions will be left in their original order. Default: All dimensions of input.    Example >>> f = torch.fft.fftfreq(4)
>>> f
tensor([ 0.0000,  0.2500, -0.5000, -0.2500])
 >>> torch.fft.fftshift(f)
tensor([-0.5000, -0.2500,  0.0000,  0.2500])
 Also notice that the Nyquist frequency term at f[2] was moved to the beginning of the tensor. This also works for multi-dimensional transforms: >>> x = torch.fft.fftfreq(5, d=1/5) + 0.1 * torch.fft.fftfreq(5, d=1/5).unsqueeze(1)
>>> x
tensor([[ 0.0000,  1.0000,  2.0000, -2.0000, -1.0000],
        [ 0.1000,  1.1000,  2.1000, -1.9000, -0.9000],
        [ 0.2000,  1.2000,  2.2000, -1.8000, -0.8000],
        [-0.2000,  0.8000,  1.8000, -2.2000, -1.2000],
        [-0.1000,  0.9000,  1.9000, -2.1000, -1.1000]])
 >>> torch.fft.fftshift(x)
tensor([[-2.2000, -1.2000, -0.2000,  0.8000,  1.8000],
        [-2.1000, -1.1000, -0.1000,  0.9000,  1.9000],
        [-2.0000, -1.0000,  0.0000,  1.0000,  2.0000],
        [-1.9000, -0.9000,  0.1000,  1.1000,  2.1000],
        [-1.8000, -0.8000,  0.2000,  1.2000,  2.2000]])
 fftshift() can also be useful for spatial data. If our data is defined on a centered grid ([-(N//2), (N-1)//2]) then we can use the standard FFT defined on an uncentered grid ([0, N)) by first applying an ifftshift(). >>> x_centered = torch.arange(-5, 5)
>>> x_uncentered = torch.fft.ifftshift(x_centered)
>>> fft_uncentered = torch.fft.fft(x_uncentered)
 Similarly, we can convert the frequency domain components to centered convention by applying fftshift(). >>> fft_centered = torch.fft.fftshift(fft_uncentered)
 The inverse transform, from centered Fourier space back to centered spatial data, can be performed by applying the inverse shifts in reverse order: >>> x_centered_2 = torch.fft.fftshift(torch.fft.ifft(torch.fft.ifftshift(fft_centered)))
>>> torch.allclose(x_centered.to(torch.complex64), x_centered_2)
True

torch.fft.ifftshift(input, dim=None) → Tensor
Inverse of fftshift().  Parameters

input (Tensor) – the tensor in FFT order
dim (int, Tuple[int], optional) – The dimensions to rearrange. Only dimensions specified here will be rearranged, any other dimensions will be left in their original order. Default: All dimensions of input.    Example >>> f = torch.fft.fftfreq(5)
>>> f
tensor([ 0.0000,  0.2000,  0.4000, -0.4000, -0.2000])
 A round-trip through fftshift() and ifftshift() gives the same result: >>> shifted = torch.fftshift(f)
>>> torch.ifftshift(shifted)
tensor([ 0.0000,  0.2000,  0.4000, -0.4000, -0.2000])


torch.fft.fft(input, n=None, dim=-1, norm=None) → Tensor
Computes the one dimensional discrete Fourier transform of input.  Note The Fourier domain representation of any real signal satisfies the Hermitian property: X[i] = conj(X[-i]). This function always returns both the positive and negative frequency terms even though, for real inputs, the negative frequencies are redundant. rfft() returns the more compact one-sided representation where only the positive frequencies are returned.   Parameters

input (Tensor) – the input tensor
n (int, optional) – Signal length. If given, the input will either be zero-padded or trimmed to this length before computing the FFT.
dim (int, optional) – The dimension along which to take the one dimensional FFT.
norm (str, optional) –
Normalization mode. For the forward transform (fft()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Calling the backward transform (ifft()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifft() the exact inverse. Default is "backward" (no normalization).     Example >>> t = torch.arange(4)
>>> t
tensor([0, 1, 2, 3])
>>> torch.fft.fft(t)
tensor([ 6.+0.j, -2.+2.j, -2.+0.j, -2.-2.j])
 >>> t = tensor([0.+1.j, 2.+3.j, 4.+5.j, 6.+7.j])
>>> torch.fft.fft(t)
tensor([12.+16.j, -8.+0.j, -4.-4.j,  0.-8.j])


torch.fft.fft2(input, s=None, dim=(-2, -1), norm=None) → Tensor
Computes the 2 dimensional discrete Fourier transform of input. Equivalent to fftn() but FFTs only the last two dimensions by default.  Note The Fourier domain representation of any real signal satisfies the Hermitian property: X[i, j] = conj(X[-i, -j]). This function always returns all positive and negative frequency terms even though, for real inputs, half of these values are redundant. rfft2() returns the more compact one-sided representation where only the positive frequencies of the last dimension are returned.   Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the FFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: last two dimensions.
norm (str, optional) –
Normalization mode. For the forward transform (fft2()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Where n = prod(s) is the logical FFT size. Calling the backward transform (ifft2()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifft2() the exact inverse. Default is "backward" (no normalization).     Example >>> x = torch.rand(10, 10, dtype=torch.complex64)
>>> fft2 = torch.fft.fft2(t)
 The discrete Fourier transform is separable, so fft2() here is equivalent to two one-dimensional fft() calls: >>> two_ffts = torch.fft.fft(torch.fft.fft(x, dim=0), dim=1)
>>> torch.allclose(fft2, two_ffts)


torch.fft.fftfreq(n, d=1.0, *, dtype=None, layout=torch.strided, device=None, requires_grad=False) → Tensor
Computes the discrete Fourier Transform sample frequencies for a signal of size n.  Note By convention, fft() returns positive frequency terms first, followed by the negative frequencies in reverse order, so that f[-i] for all 0<i≤n/20 < i \leq n/2  in Python gives the negative frequency terms. For an FFT of length n and with inputs spaced in length unit d, the frequencies are: f = [0, 1, ..., (n - 1) // 2, -(n // 2), ..., -1] / (d * n)
   Note For even lengths, the Nyquist frequency at f[n/2] can be thought of as either negative or positive. fftfreq() follows NumPy’s convention of taking it to be negative.   Parameters

n (int) – the FFT length
d (float, optional) – The sampling length scale. The spacing between individual samples of the FFT input. The default assumes unit spacing, dividing that result by the actual spacing gives the result in physical frequency units.   Keyword Arguments

dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_tensor_type()).
layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.
device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_tensor_type()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.
requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.    Example >>> torch.fft.fftfreq(5)
tensor([ 0.0000,  0.2000,  0.4000, -0.4000, -0.2000])
 For even input, we can see the Nyquist frequency at f[2] is given as negative: >>> torch.fft.fftfreq(4)
tensor([ 0.0000,  0.2500, -0.5000, -0.2500])


torch.fft.fftn(input, s=None, dim=None, norm=None) → Tensor
Computes the N dimensional discrete Fourier transform of input.  Note The Fourier domain representation of any real signal satisfies the Hermitian property: X[i_1, ..., i_n] = conj(X[-i_1, ..., -i_n]). This function always returns all positive and negative frequency terms even though, for real inputs, half of these values are redundant. rfftn() returns the more compact one-sided representation where only the positive frequencies of the last dimension are returned.   Parameters

input (Tensor) – the input tensor
s (Tuple[int], optional) – Signal size in the transformed dimensions. If given, each dimension dim[i] will either be zero-padded or trimmed to the length s[i] before computing the FFT. If a length -1 is specified, no padding is done in that dimension. Default: s = [input.size(d) for d in dim]

dim (Tuple[int], optional) – Dimensions to be transformed. Default: all dimensions, or the last len(s) dimensions if s is given.
norm (str, optional) –
Normalization mode. For the forward transform (fftn()), these correspond to:
"forward" - normalize by 1/n

"backward" - no normalization
"ortho" - normalize by 1/sqrt(n) (making the FFT orthonormal)  Where n = prod(s) is the logical FFT size. Calling the backward transform (ifftn()) with the same normalization mode will apply an overall normalization of 1/n between the two transforms. This is required to make ifftn() the exact inverse. Default is "backward" (no normalization).     Example >>> x = torch.rand(10, 10, dtype=torch.complex64)
>>> fftn = torch.fft.fftn(t)
 The discrete Fourier transform is separable, so fftn() here is equivalent to two one-dimensional fft() calls: >>> two_ffts = torch.fft.fft(torch.fft.fft(x, dim=0), dim=1)
>>> torch.allclose(fftn, two_ffts)