• 文档 >
  • 概率分布 - torch.distributions
快捷方式

概率分布 - torch.distributions

distributions 包包含可参数化的概率分布和采样函数。 这允许构建随机计算图和随机梯度估计器以进行优化。 此包通常遵循 TensorFlow Distributions 包的设计。

无法直接反向传播随机样本。 但是,有两种主要方法可以创建可以反向传播的代理函数。 这些是分数函数估计器/似然比估计器/REINFORCE 和路径导数估计器。 REINFORCE 通常被视为强化学习中策略梯度方法的基础,而路径导数估计器通常在变分自编码器中的重新参数化技巧中被看到。 虽然分数函数只需要样本值 f(x)f(x),但路径导数需要导数 f(x)f'(x)。 以下部分将在强化学习示例中讨论这两种方法。 有关更多详细信息,请参阅 Gradient Estimation Using Stochastic Computation Graphs

分数函数

当概率密度函数对其参数可微时,我们只需要 sample()log_prob() 来实现 REINFORCE

Δθ=αrlogp(aπθ(s))θ\Delta\theta = \alpha r \frac{\partial\log p(a|\pi^\theta(s))}{\partial\theta}

其中 θ\theta 是参数,α\alpha 是学习率,rr 是奖励,p(aπθ(s))p(a|\pi^\theta(s)) 是在给定策略 πθ\pi^\theta 时,在状态 ss 中采取行动 aa 的概率。

在实践中,我们会从网络输出中采样一个动作,在环境中应用此动作,然后使用 log_prob 来构建一个等效的损失函数。注意,我们使用负号,因为优化器使用梯度下降,而上面的规则假设梯度上升。对于分类策略,实现 REINFORCE 的代码如下

probs = policy_network(state)
# Note that this is equivalent to what used to be called multinomial
m = Categorical(probs)
action = m.sample()
next_state, reward = env.step(action)
loss = -m.log_prob(action) * reward
loss.backward()

路径导数

实现这些随机/策略梯度的另一种方法是使用来自 rsample() 方法的重新参数化技巧,其中参数化随机变量可以通过无参数随机变量的参数化确定性函数来构造。因此,重新参数化的样本变得可微。实现路径导数的代码如下

params = policy_network(state)
m = Normal(*params)
# Any distribution with .has_rsample == True could work based on the application
action = m.rsample()
next_state, reward = env.step(action)  # Assuming that reward is differentiable
loss = -reward
loss.backward()

分布

class torch.distributions.distribution.Distribution(batch_shape=torch.Size([]), event_shape=torch.Size([]), validate_args=None)[source]

基类: object

Distribution 是概率分布的抽象基类。

property arg_constraints: Dict[str, Constraint]

返回一个字典,其中包含从参数名称到 Constraint 对象的映射,这些对象应该满足此分布的每个参数。不属于张量的参数不需要出现在此字典中。

property batch_shape: Size

返回参数批处理的形状。

cdf(value)[source]

返回在 value 处计算的累积密度/质量函数。

参数

value (Tensor) –

返回类型

Tensor

entropy()[source]

返回分布的熵,在 batch_shape 上批处理。

返回

形状为 batch_shape 的 Tensor。

返回类型

Tensor

enumerate_support(expand=True)[source]

返回包含离散分布支持的所有值的张量。结果将枚举维度 0,因此结果的形状将为 (cardinality,) + batch_shape + event_shape(其中对于单变量分布 event_shape = ())。

请注意,这会按步进方式枚举所有批处理张量 [[0, 0], [1, 1], …]。使用 expand=False,枚举发生在 dim 0 沿,但其余的批处理维度是单一维度,[[0], [1], ..

要遍历完整的笛卡尔积,请使用 itertools.product(m.enumerate_support())

参数

expand (bool) – 是否扩展支持的批处理维度以匹配分布的 batch_shape

返回

沿维度 0 迭代的张量。

返回类型

Tensor

property event_shape: Size

返回单个样本(无批处理)的形状。

expand(batch_shape, _instance=None)[source]

返回一个新的分布实例(或填充由派生类提供的现有实例),批处理维度扩展到 batch_shape。此方法在分布的参数上调用 expand。因此,这不会为扩展的分布实例分配新内存。此外,这不会在创建实例时重复 __init__.py 中的任何参数检查或参数广播。

参数
  • batch_shape (torch.Size) – 期望的扩展大小。

  • _instance – 子类提供的需要覆盖 .expand 的新实例。

返回

批处理维度扩展到 batch_size 的新分布实例。

icdf(value)[source]

返回在 value 处计算的逆累积密度/质量函数。

参数

value (Tensor) –

返回类型

Tensor

log_prob(value)[source]

返回在 value 处计算的概率密度/质量函数的对数。

参数

value (Tensor) –

返回类型

Tensor

property mean: Tensor

返回分布的均值。

property mode: Tensor

返回分布的众数。

perplexity()[source]

返回分布的困惑度,在 batch_shape 上进行批处理。

返回

形状为 batch_shape 的 Tensor。

返回类型

Tensor

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

如果分布参数被批处理,则生成一个 sample_shape 形状的重新参数化的样本,或者一个 sample_shape 形状的重新参数化的样本批次。

返回类型

Tensor

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

如果分布参数被批处理,则生成一个 sample_shape 形状的样本,或者一个 sample_shape 形状的样本批次。

返回类型

Tensor

sample_n(n)[source]

如果分布参数被批处理,则生成 n 个样本,或者 n 个样本批次。

返回类型

Tensor

static set_default_validate_args(value)[source]

设置是否启用验证。

默认行为模仿 Python 的 assert 语句:默认情况下验证处于启用状态,但如果 Python 在优化模式下运行(通过 python -O),则会禁用验证。验证可能很昂贵,因此您可能希望在模型正常工作后禁用它。

参数

value (bool) – 是否启用验证。

property stddev: Tensor

返回分布的标准差。

property support: Optional[Any]

返回一个 Constraint 对象,表示该分布的支持。

property variance: Tensor

返回分布的方差。

ExponentialFamily

class torch.distributions.exp_family.ExponentialFamily(batch_shape=torch.Size([]), event_shape=torch.Size([]), validate_args=None)[source]

Bases: Distribution

ExponentialFamily 是属于指数族概率分布的抽象基类,其概率质量/密度函数的形式如下

pF(x;θ)=exp(t(x),θF(θ)+k(x))p_{F}(x; \theta) = \exp(\langle t(x), \theta\rangle - F(\theta) + k(x))

其中 θ\theta 表示自然参数,t(x)t(x) 表示充分统计量,F(θ)F(\theta) 是给定族的对数归一化函数,而 k(x)k(x) 是载体测度。

注意

此类是 Distribution 类和属于指数族的分布之间的中间类,主要用于检查 .entropy() 和解析 KL 散度方法的正确性。我们使用此类来使用 AD 框架和 Bregman 散度(由:Frank Nielsen 和 Richard Nock 提供,指数族的熵和交叉熵)计算熵和 KL 散度。

entropy()[source]

使用对数归一化器的 Bregman 散度计算熵的方法。

Bernoulli

class torch.distributions.bernoulli.Bernoulli(probs=None, logits=None, validate_args=None)[source]

Bases: ExponentialFamily

创建一个由 probslogits 参数化的伯努利分布(但不能同时使用两者)。

样本是二进制的(0 或 1)。它们以概率 p 采用值 1,以概率 1 - p 采用值 0

示例

>>> m = Bernoulli(torch.tensor([0.3]))
>>> m.sample()  # 30% chance 1; 70% chance 0
tensor([ 0.])
参数
  • probs (Number, Tensor) – 采样 1 的概率

  • logits (Number, Tensor) – 采样 1 的对数几率

arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}
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 mode
property param_shape
property probs
sample(sample_shape=torch.Size([]))[source]
support = Boolean()
property variance

Beta

class torch.distributions.beta.Beta(concentration1, concentration0, validate_args=None)[source]

Bases: ExponentialFamily

concentration1concentration0 参数化的 Beta 分布。

示例

>>> m = Beta(torch.tensor([0.5]), torch.tensor([0.5]))
>>> m.sample()  # Beta distributed with concentration concentration1 and concentration0
tensor([ 0.1046])
参数
  • concentration1 (float or Tensor) – 分布的第一个浓度参数(通常称为 alpha)

  • concentration0 (float or Tensor) – 分布的第二个浓度参数(通常称为 beta)

arg_constraints = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0)}
property concentration0
property concentration1
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
rsample(sample_shape=())[source]
support = Interval(lower_bound=0.0, upper_bound=1.0)
property variance

Binomial

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

Bases: Distribution

创建一个二项式分布,由 total_count 参数化,并由 probslogits 参数化(但不能同时参数化)。total_count 必须是可广播的,与 probs/logits 可广播。

示例

>>> m = Binomial(100, torch.tensor([0 , .2, .8, 1]))
>>> x = m.sample()
tensor([   0.,   22.,   71.,  100.])

>>> m = Binomial(torch.tensor([[5.], [10.]]), torch.tensor([0.5, 0.8]))
>>> x = m.sample()
tensor([[ 4.,  5.],
        [ 7.,  6.]])
参数
  • total_count (int or Tensor) – 伯努利试验次数

  • probs (Tensor) – 事件概率

  • logits (Tensor) – 事件对数几率

arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0), 'total_count': IntegerGreaterThan(lower_bound=0)}
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 mode
property param_shape
property probs
sample(sample_shape=torch.Size([]))[source]
property support
property variance

Categorical

class torch.distributions.categorical.Categorical(probs=None, logits=None, validate_args=None)[source]

Bases: Distribution

创建由 probslogits(但不是两者)参数化的类别分布。

注意

它等效于 torch.multinomial() 从中采样的分布。

样本是来自 {0,,K1}\{0, \ldots, K-1\} 的整数,其中 Kprobs.size(-1)

如果 probs 是长度为 K 的一维数组,则每个元素是采样该索引处的类的相对概率。

如果 probs 是 N 维数组,则前 N-1 维被视为相对概率向量的批次。

注意

probs 参数必须是非负、有限的并且具有非零的和,它将在最后一个维度上被归一化为和为 1。 probs 将返回此归一化值。 logits 参数将被解释为未归一化的对数概率,因此可以是任何实数。它同样会被归一化,使得结果概率在最后一个维度上总和为 1。 logits 将返回此归一化值。

另请参阅:

参数
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 mode
property param_shape
property probs
sample(sample_shape=torch.Size([]))[source]
property support
property variance

Cauchy

class torch.distributions.cauchy.Cauchy(loc, scale, validate_args=None)[source]

Bases: Distribution

从柯西(洛伦兹)分布中采样。独立正态分布随机变量的比率的分布,其均值为 0 遵循柯西分布。

示例

>>> m = Cauchy(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Cauchy distribution with loc=0 and scale=1
tensor([ 2.3214])
参数
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
property mode
rsample(sample_shape=torch.Size([]))[source]
support = Real()
property variance

卡方

class torch.distributions.chi2.Chi2(df, validate_args=None)[source]

基类: Gamma

创建一个卡方分布,其参数为形状参数 df。这与 Gamma(alpha=0.5*df, beta=0.5) 完全等效。

示例

>>> m = Chi2(torch.tensor([1.0]))
>>> m.sample()  # Chi2 distributed with shape df=1
tensor([ 0.1046])
参数

df (floatTensor) – 分布的形状参数

arg_constraints = {'df': GreaterThan(lower_bound=0.0)}
property df
expand(batch_shape, _instance=None)[source]

连续伯努利

class torch.distributions.continuous_bernoulli.ContinuousBernoulli(probs=None, logits=None, lims=(0.499, 0.501), validate_args=None)[source]

Bases: ExponentialFamily

创建一个连续伯努利分布,其参数为 probslogits(但不能同时使用两者)。

该分布在 [0, 1] 中有支持,并且由‘probs’(在 (0,1) 中)或‘logits’(实值)参数化。请注意,与伯努利分布不同,‘probs’ 不对应于概率,‘logits’ 不对应于对数几率,但由于与伯努利分布的相似性,使用了相同的名称。有关更多详细信息,请参见 [1]。

示例

>>> m = ContinuousBernoulli(torch.tensor([0.3]))
>>> m.sample()
tensor([ 0.2538])
参数
  • probs (Number, Tensor) – (0,1) 值参数

  • logits (Number, Tensor) – 实值参数,其 sigmoid 与‘probs’ 相匹配

[1] 连续伯努利:修复变分自编码器中普遍存在的错误,Loaiza-Ganem G 和 Cunningham JP,NeurIPS 2019。 https://arxiv.org/abs/1907.06845

arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}
cdf(value)[source]
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
icdf(value)[source]
log_prob(value)[source]
property logits
property mean
property param_shape
property probs
rsample(sample_shape=torch.Size([]))[source]
sample(sample_shape=torch.Size([]))[source]
property stddev
support = Interval(lower_bound=0.0, upper_bound=1.0)
property variance

Dirichlet

class torch.distributions.dirichlet.Dirichlet(concentration, validate_args=None)[source]

Bases: ExponentialFamily

创建一个由浓度参数化的狄利克雷分布 concentration

示例

>>> m = Dirichlet(torch.tensor([0.5, 0.5]))
>>> m.sample()  # Dirichlet distributed with concentration [0.5, 0.5]
tensor([ 0.1046,  0.8954])
参数

concentration (Tensor) – 分布的浓度参数(通常称为 alpha)

arg_constraints = {'concentration': IndependentConstraint(GreaterThan(lower_bound=0.0), 1)}
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
rsample(sample_shape=())[source]
support = Simplex()
property variance

Exponential

class torch.distributions.exponential.Exponential(rate, validate_args=None)[source]

Bases: ExponentialFamily

创建一个由 rate 参数化的指数分布。

示例

>>> m = Exponential(torch.tensor([1.0]))
>>> m.sample()  # Exponential distributed with rate=1
tensor([ 0.1046])
参数

rate (float or Tensor) – rate = 1 / scale of the distribution

arg_constraints = {'rate': 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
property mode
rsample(sample_shape=torch.Size([]))[source]
property stddev
support = GreaterThanEq(lower_bound=0.0)
property variance

FisherSnedecor

class torch.distributions.fishersnedecor.FisherSnedecor(df1, df2, validate_args=None)[source]

Bases: Distribution

创建一个由 df1df2 参数化的费希尔-斯尼德科分布。

示例

>>> m = FisherSnedecor(torch.tensor([1.0]), torch.tensor([2.0]))
>>> m.sample()  # Fisher-Snedecor-distributed with df1=1 and df2=2
tensor([ 0.2453])
参数
arg_constraints = {'df1': GreaterThan(lower_bound=0.0), 'df2': GreaterThan(lower_bound=0.0)}
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
rsample(sample_shape=torch.Size([]))[source]
support = GreaterThan(lower_bound=0.0)
property variance

Gamma

class torch.distributions.gamma.Gamma(concentration, rate, validate_args=None)[source]

Bases: ExponentialFamily

创建一个由形状参数化的 Gamma 分布 concentrationrate

示例

>>> m = Gamma(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # Gamma distributed with concentration=1 and rate=1
tensor([ 0.1046])
参数
  • concentration (float or Tensor) – 分布的形状参数(通常称为 alpha)

  • rate (float or Tensor) – rate = 1 / scale of the distribution (often referred to as beta)

arg_constraints = {'concentration': GreaterThan(lower_bound=0.0), 'rate': GreaterThan(lower_bound=0.0)}
cdf(value)[source]
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
rsample(sample_shape=torch.Size([]))[source]
support = GreaterThanEq(lower_bound=0.0)
property variance

Geometric

class torch.distributions.geometric.Geometric(probs=None, logits=None, validate_args=None)[source]

Bases: Distribution

创建一个由 probs 参数化的几何分布,其中 probs 是伯努利试验成功的概率。

P(X=k)=(1p)kp,k=0,1,...P(X=k) = (1-p)^{k} p, k = 0, 1, ...

注意

torch.distributions.geometric.Geometric() (k+1)(k+1)-th trial is the first success hence draws samples in {0,1,}\{0, 1, \ldots\}, whereas torch.Tensor.geometric_() k-th trial is the first success hence draws samples in {1,2,}\{1, 2, \ldots\}.

示例

>>> m = Geometric(torch.tensor([0.3]))
>>> m.sample()  # underlying Bernoulli has 30% chance 1; 70% chance 0
tensor([ 2.])
参数
  • probs (Number, Tensor) – 采样 1 的概率。必须在范围内 (0, 1]

  • logits (Number, Tensor) – 采样 1 的 log-odds。

arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0)}
entropy()[source]
expand(batch_shape, _instance=None)[source]
log_prob(value)[source]
property logits
property mean
property mode
property probs
sample(sample_shape=torch.Size([]))[source]
support = IntegerGreaterThan(lower_bound=0)
property variance

Gumbel

class torch.distributions.gumbel.Gumbel(loc, scale, validate_args=None)[source]

Bases: TransformedDistribution

从 Gumbel 分布中采样。

示例

>>> m = Gumbel(torch.tensor([1.0]), torch.tensor([2.0]))
>>> m.sample()  # sample from Gumbel distribution with loc=1, scale=2
tensor([ 1.0124])
参数
arg_constraints: Dict[str, Constraint] = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}
entropy()[source]
expand(batch_shape, _instance=None)[source]
log_prob(value)[source]
property mean
property mode
property stddev
support = Real()
property variance

HalfCauchy

class torch.distributions.half_cauchy.HalfCauchy(scale, validate_args=None)[source]

Bases: TransformedDistribution

创建由 scale 参数化的半柯西分布,其中

X ~ Cauchy(0, scale)
Y = |X| ~ HalfCauchy(scale)

示例

>>> m = HalfCauchy(torch.tensor([1.0]))
>>> m.sample()  # half-cauchy distributed with scale=1
tensor([ 2.3214])
参数

scale (float张量) – 完整柯西分布的尺度

arg_constraints: Dict[str, Constraint] = {'scale': GreaterThan(lower_bound=0.0)}
cdf(value)[source]
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
icdf(prob)[source]
log_prob(value)[source]
property mean
property mode
property scale
support = GreaterThanEq(lower_bound=0.0)
property variance

HalfNormal

class torch.distributions.half_normal.HalfNormal(scale, validate_args=None)[source]

Bases: TransformedDistribution

创建由 scale 参数化的半正态分布,其中

X ~ Normal(0, scale)
Y = |X| ~ HalfNormal(scale)

示例

>>> m = HalfNormal(torch.tensor([1.0]))
>>> m.sample()  # half-normal distributed with scale=1
tensor([ 0.1046])
参数

scale (float or Tensor) – 完整正态分布的尺度

arg_constraints: Dict[str, Constraint] = {'scale': GreaterThan(lower_bound=0.0)}
cdf(value)[source]
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
icdf(prob)[source]
log_prob(value)[source]
property mean
property mode
property scale
support = GreaterThanEq(lower_bound=0.0)
property variance

Independent

class torch.distributions.independent.Independent(base_distribution, reinterpreted_batch_ndims, validate_args=None)[source]

Bases: Distribution

将分布的一些批次维度重新解释为事件维度。

这主要用于更改 log_prob() 结果的形状。例如,要创建与多元正态分布具有相同形状的对角正态分布(因此它们可以互换),您可以

>>> from torch.distributions.multivariate_normal import MultivariateNormal
>>> from torch.distributions.normal import Normal
>>> loc = torch.zeros(3)
>>> scale = torch.ones(3)
>>> mvn = MultivariateNormal(loc, scale_tril=torch.diag(scale))
>>> [mvn.batch_shape, mvn.event_shape]
[torch.Size([]), torch.Size([3])]
>>> normal = Normal(loc, scale)
>>> [normal.batch_shape, normal.event_shape]
[torch.Size([3]), torch.Size([])]
>>> diagn = Independent(normal, 1)
>>> [diagn.batch_shape, diagn.event_shape]
[torch.Size([]), torch.Size([3])]
参数
arg_constraints: Dict[str, Constraint] = {}
entropy()[source]
enumerate_support(expand=True)[source]
expand(batch_shape, _instance=None)[source]
property has_enumerate_support
property has_rsample
log_prob(value)[source]
property mean
property mode
rsample(sample_shape=torch.Size([]))[source]
sample(sample_shape=torch.Size([]))[source]
property support
property variance

InverseGamma

class torch.distributions.inverse_gamma.InverseGamma(concentration, rate, validate_args=None)[source]

Bases: TransformedDistribution

创建由 concentrationrate 参数化的逆伽马分布,其中

X ~ Gamma(concentration, rate)
Y = 1 / X ~ InverseGamma(concentration, rate)

示例

>>> m = InverseGamma(torch.tensor([2.0]), torch.tensor([3.0]))
>>> m.sample()
tensor([ 1.2953])
参数
  • concentration (float or Tensor) – 分布的形状参数(通常称为 alpha)

  • rate (float or Tensor) – rate = 1 / scale of the distribution (often referred to as beta)

arg_constraints: Dict[str, Constraint] = {'concentration': GreaterThan(lower_bound=0.0), 'rate': GreaterThan(lower_bound=0.0)}
property concentration
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
property mean
property mode
property rate
support = GreaterThan(lower_bound=0.0)
property variance

Kumaraswamy

class torch.distributions.kumaraswamy.Kumaraswamy(concentration1, concentration0, validate_args=None)[source]

Bases: TransformedDistribution

从 Kumaraswamy 分布中采样。

示例

>>> m = Kumaraswamy(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Kumaraswamy distribution with concentration alpha=1 and beta=1
tensor([ 0.1729])
参数
  • concentration1 (float or Tensor) – 分布的第一个浓度参数(通常称为 alpha)

  • concentration0 (float or Tensor) – 分布的第二个浓度参数(通常称为 beta)

arg_constraints: Dict[str, Constraint] = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0)}
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
property mean
property mode
support = Interval(lower_bound=0.0, upper_bound=1.0)
property variance

LKJCholesky

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

Bases: Distribution

用于相关矩阵的较低 Cholesky 因子的 LKJ 分布。该分布由 concentration 参数 η\eta 控制,以使从 Cholesky 因子生成的 correlation matrix MM 的概率与 det(M)η1\det(M)^{\eta - 1} 成正比。因此,当 concentration == 1 时,我们在相关矩阵的 Cholesky 因子上有均匀分布。

L ~ LKJCholesky(dim, concentration)
X = L @ L' ~ LKJCorr(dim, concentration)

请注意,此分布对相关矩阵的 Cholesky 因子进行采样,而不是相关矩阵本身,因此与 [1] 中对 LKJCorr 分布的推导略有不同。对于采样,这使用了 [1] 第 3 节中的 Onion 方法。

示例

>>> 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]])
参数
  • 维度 (dim) – 矩阵的维度

  • 浓度 (floatTensor) – 分布的浓度/形状参数(通常称为 eta)

参考

[1] 基于藤和扩展洋葱方法生成随机相关矩阵 (2009),Daniel Lewandowski、Dorota Kurowicka、Harry Joe。多元分析杂志。100. 10.1016/j.jmva.2009.04.008

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

Laplace

class torch.distributions.laplace.Laplace(loc, scale, validate_args=None)[source]

Bases: Distribution

创建一个由 locscale 参数化的 Laplace 分布。

示例

>>> m = Laplace(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # Laplace distributed with loc=0, scale=1
tensor([ 0.1046])
参数
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
property mode
rsample(sample_shape=torch.Size([]))[source]
property stddev
support = Real()
property variance

LogNormal

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

Bases: TransformedDistribution

创建一个对数正态分布,由 locscale 参数化,其中

X ~ Normal(loc, scale)
Y = exp(X) ~ LogNormal(loc, scale)

示例

>>> m = LogNormal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # log-normal distributed with mean=0 and stddev=1
tensor([ 0.1046])
参数
arg_constraints: Dict[str, 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 mode
property scale
support = GreaterThan(lower_bound=0.0)
property variance

LowRankMultivariateNormal

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

Bases: Distribution

创建一个多元正态分布,其协方差矩阵具有低秩形式,由 cov_factorcov_diag 参数化

covariance_matrix = cov_factor @ cov_factor.T + cov_diag

示例

>>> 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])
参数
  • loc (Tensor) – 分布的均值,形状为 batch_shape + event_shape

  • cov_factor (Tensor) – 协方差矩阵低秩形式的因子部分,形状为 batch_shape + event_shape + (rank,)

  • cov_diag (Tensor) – 协方差矩阵低秩形式的对角部分,形状为 batch_shape + event_shape

注意

cov_factor.shape[1] << cov_factor.shape[0] 时,协方差矩阵的行列式和逆矩阵的计算将被避免,这得益于 Woodbury 矩阵恒等式矩阵行列式引理。由于这些公式,我们只需要计算小尺寸“电容”矩阵的行列式和逆矩阵

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)}
property covariance_matrix
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
property precision_matrix
rsample(sample_shape=torch.Size([]))[source]
property scale_tril
support = IndependentConstraint(Real(), 1)
property variance

MixtureSameFamily

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

Bases: 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.

示例

>>> # 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 Model 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)
参数
  • mixture_distributiontorch.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_distributiontorch.distributions.Distribution-like instance. Right-most batch dimension indexes component.

arg_constraints: Dict[str, 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

Multinomial

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

Bases: 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)

注意

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

示例

>>> 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])
参数
  • total_count (int) – number of trials

  • probs (Tensor) – 事件概率

  • logits (Tensor) – 事件对数概率(未归一化)

arg_constraints = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}
entropy()[source]
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
property variance

MultivariateNormal

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

Bases: Distribution

创建多元正态(也称为高斯)分布,由均值向量和协方差矩阵参数化。

多元正态分布可以用正定协方差矩阵 Σ\mathbf{\Sigma} 或正定精度矩阵 Σ1\mathbf{\Sigma}^{-1} 或下三角矩阵 L\mathbf{L}(对角线元素为正值)进行参数化,使得 Σ=LL\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top. 这个三角矩阵可以通过例如协方差的 Cholesky 分解获得。

示例

>>> 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])
参数
  • loc (Tensor) – 分布的均值

  • covariance_matrix (Tensor) – 正定协方差矩阵

  • precision_matrix (Tensor) – 正定精度矩阵

  • scale_tril (Tensor) – 协方差的下三角因子,对角线元素为正值

注意

只能指定 covariance_matrixprecision_matrixscale_tril 之一。

使用 scale_tril 将更有效:所有内部计算都基于 scale_tril。如果传递了 covariance_matrixprecision_matrix,它仅用于使用 Cholesky 分解计算相应的下三角矩阵。

arg_constraints = {'covariance_matrix': PositiveDefinite(), 'loc': IndependentConstraint(Real(), 1), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
property covariance_matrix
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
property precision_matrix
rsample(sample_shape=torch.Size([]))[source]
property scale_tril
support = IndependentConstraint(Real(), 1)
property variance

NegativeBinomial

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

Bases: Distribution

创建一个负二项分布,即在达到 total_count 次失败之前,成功独立且相同的伯努利试验次数的分布。每次伯努利试验成功的概率为 probs

参数
  • total_count (floatTensor) – 停止的负伯努利试验的非负数,尽管对于实值计数,分布仍然有效

  • probs (Tensor) – 半开区间 [0, 1) 中成功的事件概率

  • logits (Tensor) – 成功的事件对数几率

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]
property logits
property mean
property mode
property param_shape
property probs
sample(sample_shape=torch.Size([]))[source]
support = IntegerGreaterThan(lower_bound=0)
property variance

Normal

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

Bases: ExponentialFamily

创建一个正态(也称为高斯)分布,由 locscale 参数化。

示例

>>> m = Normal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # normally distributed with loc=0 and scale=1
tensor([ 0.1046])
参数
  • loc (floatTensor) – 分布的均值(通常称为 mu)

  • scale (floatTensor) – 分布的标准差(通常称为 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
property mode
rsample(sample_shape=torch.Size([]))[source]
sample(sample_shape=torch.Size([]))[source]
property stddev
support = Real()
property variance

OneHotCategorical

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

Bases: Distribution

创建一个由 probslogits 参数化的单热分类分布。

样本是一维热编码向量,大小为 probs.size(-1)

注意

probs 参数必须为非负数、有限数且和不为零,它将被归一化为最后一个维度上的总和为 1。 probs 将返回此归一化值。 logits 参数将被解释为非归一化的对数概率,因此可以是任何实数。它也将被归一化,以便得到的概率在最后一个维度上的总和为 1。 logits 将返回此归一化值。

另见: torch.distributions.Categorical() 用于指定 probslogits

示例

>>> 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.])
参数
  • probs (Tensor) – 事件概率

  • logits (Tensor) – 事件对数概率(未归一化)

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 mode
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: TransformedDistribution

从帕累托 I 型分布中采样。

示例

>>> 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])
参数
arg_constraints: Dict[str, Constraint] = {'alpha': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}
entropy()[source]
expand(batch_shape, _instance=None)[source]
property mean
property mode
property support
property variance

泊松分布

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

Bases: ExponentialFamily

创建由 rate 参数化的泊松分布,它是速率参数。

样本是非负整数,其概率质量函数由下式给出

ratekeratek!\mathrm{rate}^k \frac{e^{-\mathrm{rate}}}{k!}

示例

>>> m = Poisson(torch.tensor([4]))
>>> m.sample()
tensor([ 3.])
参数

rate (数字, 张量) – 速率参数

arg_constraints = {'rate': GreaterThanEq(lower_bound=0.0)}
expand(batch_shape, _instance=None)[source]
log_prob(value)[source]
property mean
property mode
sample(sample_shape=torch.Size([]))[source]
support = IntegerGreaterThan(lower_bound=0)
property variance

RelaxedBernoulli

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

Bases: TransformedDistribution

创建一个 RelaxedBernoulli 分布,由 temperature 参数化,以及 probslogits(但不能同时使用两者)。这是一个松弛版本的 Bernoulli 分布,因此值在 (0, 1) 中,并且具有可重参数化的样本。

示例

>>> 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])
参数
  • temperature (Tensor) – 松弛温度

  • probs (Number, Tensor) – 采样 1 的概率

  • logits (Number, Tensor) – 采样 1 的对数几率

arg_constraints: Dict[str, 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

LogitRelaxedBernoulli

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

Bases: Distribution

创建一个 LogitRelaxedBernoulli 分布,由 probslogits(但不能同时使用两者)参数化,它是 RelaxedBernoulli 分布的 logit。

样本是 (0, 1) 中值的 logit。有关更多详细信息,请参阅 [1]。

参数
  • temperature (Tensor) – 松弛温度

  • probs (Number, Tensor) – 采样 1 的概率

  • logits (Number, Tensor) – 采样 1 的对数几率

[1] The Concrete Distribution: A Continuous Relaxation of Discrete Random Variables (Maddison 等人,2017 年)

[2] Categorical Reparametrization with Gumbel-Softmax (Jang 等人,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]
property logits
property param_shape
property probs
rsample(sample_shape=torch.Size([]))[source]
support = Real()

RelaxedOneHotCategorical

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

Bases: TransformedDistribution

创建一个由 temperature 参数化的 RelaxedOneHotCategorical 分布,以及 probslogits。 这是一个 OneHotCategorical 分布的松弛版本,因此它的样本在单纯形上,并且是可重新参数化的。

示例

>>> 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])
参数
  • temperature (Tensor) – 松弛温度

  • probs (Tensor) – 事件概率

  • logits (Tensor) – 每个事件的非归一化对数概率

arg_constraints: Dict[str, Constraint] = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}
expand(batch_shape, _instance=None)[source]
has_rsample = True
property logits
property probs
support = Simplex()
property temperature

学生t分布

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

Bases: Distribution

创建一个由自由度 df,均值 loc 和尺度 scale 参数化的学生 t 分布。

示例

>>> m = StudentT(torch.tensor([2.0]))
>>> m.sample()  # Student's t-distributed with degrees of freedom=2
tensor([ 0.1046])
参数
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
property mode
rsample(sample_shape=torch.Size([]))[source]
support = Real()
property variance

变换分布

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

Bases: Distribution

Distribution 类的扩展,它将一系列变换应用于基本分布。 令 f 为应用变换的组合

X ~ BaseDistribution
Y = f(X) ~ TransformedDistribution(BaseDistribution, f)
log p(Y) = log p(X) + log |det (dX/dY)|

注意,TransformedDistribution.event_shape 是其基本分布和变换的最大形状,因为变换会在事件之间引入相关性。

使用 TransformedDistribution 的示例是

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

有关更多示例,请查看 GumbelHalfCauchyHalfNormalLogNormalParetoWeibullRelaxedBernoulliRelaxedOneHotCategorical 的实现。

arg_constraints: Dict[str, Constraint] = {}
cdf(value)[source]

通过反转变换并计算基本分布的得分来计算累积分布函数。

expand(batch_shape, _instance=None)[source]
property has_rsample
icdf(value)[source]

使用变换计算逆累积分布函数,并计算基本分布的得分。

log_prob(value)[source]

通过反转变换并使用基本分布的得分和对数绝对行列式雅可比行列式计算得分来对样本进行评分。

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

如果分布参数是批量的,则生成一个 sample_shape 形状的重新参数化样本或 sample_shape 形状的重新参数化样本批次。首先从基本分布中采样,然后对列表中的每个变换应用 transform()

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

如果分布参数是批量的,则生成一个 sample_shape 形状的样本或 sample_shape 形状的样本批次。首先从基本分布中采样,然后对列表中的每个变换应用 transform()

property support

Uniform

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

Bases: Distribution

从半开区间 [low, high) 中生成均匀分布的随机样本。

示例

>>> m = Uniform(torch.tensor([0.0]), torch.tensor([5.0]))
>>> m.sample()  # uniformly distributed in the range [0.0, 5.0)
tensor([ 2.3418])
参数
  • low (float or Tensor) – 下限范围(包含)。

  • high (float or Tensor) – 上限范围(不包含)。

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
property mode
rsample(sample_shape=torch.Size([]))[source]
property stddev
property support
property variance

VonMises

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

Bases: Distribution

圆形 von Mises 分布。

此实现使用极坐标。 locvalue 参数可以是任何实数(便于无约束优化),但被解释为 2 pi 模的角度。

示例:
>>> m = VonMises(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # von Mises distributed with loc=1 and concentration=1
tensor([1.9777])
参数
arg_constraints = {'concentration': GreaterThan(lower_bound=0.0), 'loc': Real()}
expand(batch_shape)[source]
has_rsample = False
log_prob(value)[source]
property mean

提供的均值是圆形的。

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

von Mises 分布的采样算法基于以下论文:D.J. Best 和 N.I. Fisher,“von Mises 分布的有效模拟”。应用统计(1979):152-157。

采样始终在内部以双精度进行,以避免在 _rejection_sample() 中对于较小的集中度值出现挂起,这种挂起对于单精度来说大约在 1e-4 附近开始出现(参见问题 #88443)。

support = Real()
property variance

提供的方差是圆形的。

Weibull

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

Bases: TransformedDistribution

从双参数威布尔分布中采样。

示例

>>> 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])
参数
  • scale (floatTensor) – 分布的尺度参数 (lambda)。

  • concentration (floatTensor) – 分布的浓度参数 (k/形状)。

arg_constraints: Dict[str, Constraint] = {'concentration': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}
entropy()[source]
expand(batch_shape, _instance=None)[source]
property mean
property mode
support = GreaterThan(lower_bound=0.0)
property variance

Wishart

class torch.distributions.wishart.Wishart(df, covariance_matrix=None, precision_matrix=None, scale_tril=None, validate_args=None)[source]

Bases: ExponentialFamily

创建一个 Wishart 分布,该分布由对称正定矩阵 Σ\Sigma 或其 Cholesky 分解 Σ=LL\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top

示例

>>> m = Wishart(torch.Tensor([2]), covariance_matrix=torch.eye(2))
>>> m.sample()  # Wishart distributed with mean=`df * I` and
>>>             # variance(x_ij)=`df` for i != j and variance(x_ij)=`2 * df` for i == j
参数
  • df (floatTensor) – 大于 (平方矩阵的维数) - 1 的实数值参数。

  • covariance_matrix (Tensor) – 正定协方差矩阵

  • precision_matrix (Tensor) – 正定精度矩阵

  • scale_tril (Tensor) – 协方差的下三角因子,对角线元素为正值

注意

只能指定 covariance_matrixprecision_matrixscale_tril 之一。使用 scale_tril 将更高效:所有内部计算都基于 scale_tril。如果传递了 covariance_matrixprecision_matrix,则它仅用于使用 Cholesky 分解计算相应的下三角矩阵。‘torch.distributions.LKJCholesky’ 是一个受限的 Wishart 分布。[1]

参考

[1] Wang, Z., Wu, Y. and Chu, H., 2018. 关于 LKJ 分布和受限 Wishart 分布的等价性. [2] Sawyer, S., 2007. Wishart 分布和逆 Wishart 采样. [3] Anderson, T. W., 2003. 多元统计分析导论 (第 3 版). [4] Odell, P. L. & Feiveson, A. H., 1966. 生成样本协方差矩阵的数值过程. JASA, 61(313):199-203. [5] Ku, Y.-C. & Bloomfield, P., 2010. 在 OX 中生成具有分数自由度的随机 Wishart 矩阵.

arg_constraints = {'covariance_matrix': PositiveDefinite(), 'df': GreaterThan(lower_bound=0), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
property covariance_matrix
entropy()[source]
expand(batch_shape, _instance=None)[source]
has_rsample = True
log_prob(value)[source]
property mean
property mode
property precision_matrix
rsample(sample_shape=torch.Size([]), max_try_correction=None)[source]

警告

在某些情况下,基于 Bartlett 分解的采样算法可能会返回奇异矩阵样本。默认情况下会进行多次尝试来修正奇异样本,但最终可能仍然会返回奇异矩阵样本。奇异样本可能会在 .log_prob() 中返回 -inf 值。在这种情况下,用户应验证样本,并相应地修正 df 的值或调整 .rsample 中参数的 max_try_correction 值。

property scale_tril
support = PositiveDefinite()
property variance

KL Divergence

torch.distributions.kl.kl_divergence(p, q)[source]

计算两个分布之间的 Kullback-Leibler 散度 KL(pq)KL(p \| q).

KL(pq)=p(x)logp(x)q(x)dxKL(p \| q) = \int p(x) \log\frac {p(x)} {q(x)} \,dx
参数
返回

形状为 batch_shape 的 KL 散度批次。

返回类型

Tensor

引发

NotImplementedError – 如果分布类型未通过 register_kl() 注册。

目前已针对以下分布对实现 KL 散度
  • BernoulliBernoulli

  • BernoulliPoisson

  • BetaBeta

  • BetaContinuousBernoulli

  • BetaExponential

  • BetaGamma

  • BetaNormal

  • BetaPareto

  • BetaUniform

  • BinomialBinomial

  • CategoricalCategorical

  • CauchyCauchy

  • ContinuousBernoulliContinuousBernoulli

  • ContinuousBernoulliExponential

  • ContinuousBernoulliNormal

  • ContinuousBernoulliPareto

  • ContinuousBernoulliUniform

  • DirichletDirichlet

  • ExponentialBeta

  • ExponentialContinuousBernoulli

  • ExponentialExponential

  • ExponentialGamma

  • ExponentialGumbel

  • ExponentialNormal

  • ExponentialPareto

  • ExponentialUniform

  • ExponentialFamilyExponentialFamily

  • GammaBeta

  • GammaContinuousBernoulli

  • GammaExponential

  • GammaGamma

  • GammaGumbel

  • GammaNormal

  • GammaPareto

  • GammaUniform

  • GeometricGeometric

  • GumbelBeta

  • GumbelContinuousBernoulli

  • GumbelExponential

  • GumbelGamma

  • GumbelGumbel

  • GumbelNormal

  • GumbelPareto

  • GumbelUniform

  • HalfNormalHalfNormal

  • IndependentIndependent

  • LaplaceBeta

  • LaplaceContinuousBernoulli

  • LaplaceExponential

  • LaplaceGamma

  • LaplaceLaplace

  • LaplaceNormal

  • LaplacePareto

  • LaplaceUniform

  • LowRankMultivariateNormalLowRankMultivariateNormal

  • LowRankMultivariateNormalMultivariateNormal

  • MultivariateNormalLowRankMultivariateNormal

  • MultivariateNormalMultivariateNormal

  • NormalBeta

  • NormalContinuousBernoulli

  • NormalExponential

  • NormalGamma

  • NormalGumbel

  • NormalLaplace

  • NormalNormal

  • NormalPareto

  • NormalUniform

  • OneHotCategoricalOneHotCategorical

  • ParetoBeta

  • ParetoContinuousBernoulli

  • ParetoExponential

  • ParetoGamma

  • ParetoNormal

  • ParetoPareto

  • ParetoUniform

  • PoissonBernoulli

  • PoissonBinomial

  • PoissonPoisson

  • TransformedDistributionTransformedDistribution

  • UniformBeta

  • UniformContinuousBernoulli

  • UniformExponential

  • UniformGamma

  • UniformGumbel

  • UniformNormal

  • UniformPareto

  • UniformUniform

torch.distributions.kl.register_kl(type_p, type_q)[source]

用于注册与 kl_divergence() 配对的函数的装饰器。使用方法

@register_kl(Normal, Normal)
def kl_normal_normal(p, q):
    # insert implementation here

查找返回最具体的(类型,类型)匹配,按子类排序。如果匹配不明确,则会引发 RuntimeWarning。例如,为了解决不明确的情况

@register_kl(BaseP, DerivedQ)
def kl_version1(p, q): ...
@register_kl(DerivedP, BaseQ)
def kl_version2(p, q): ...

您应该注册第三个最具体的实现,例如

register_kl(DerivedP, DerivedQ)(kl_version1)  # Break the tie.
参数
  • type_p (type) – Distribution 的子类。

  • type_q (type) – Distribution 的子类。

Transforms

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

通过映射 y=xy = |x| 进行变换。

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

通过逐点仿射映射 y=loc+scale×xy = \text{loc} + \text{scale} \times x 进行变换。

参数
  • loc (Tensor or float) – 位置参数。

  • scale (Tensor or float) – 尺度参数。

  • event_dim (int) – event_shape 的可选大小。对于单变量随机变量,这应该为零;对于向量上的分布,这应该为 1;对于矩阵上的分布,这应该为 2,等等。

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

变换函数,将变换序列 tseq 按组件方式应用于 dim 处的每个子矩阵,子矩阵的长度为 lengths[dim],这与 torch.cat() 兼容。

示例

x0 = torch.cat([torch.range(1, 10), torch.range(1, 10)], dim=0)
x = torch.cat([x0, x0], dim=0)
t0 = CatTransform([ExpTransform(), identity_transform], dim=0, lengths=[10, 10])
t = CatTransform([t0, t0], dim=0, lengths=[20, 20])
y = t(x)
class torch.distributions.transforms.ComposeTransform(parts, cache_size=0)[source]

将多个变换组合成一个链。组合的变换负责缓存。

参数
  • parts (list of Transform) – 要组合的变换列表。

  • cache_size (int) – 缓存的大小。如果为零,则不进行缓存。如果为一,则缓存最新的单个值。仅支持 0 和 1。

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

将一个无约束的实数向量 xx(长度为 D(D1)/2D*(D-1)/2)转换为 D 维相关矩阵的 Cholesky 因子。该 Cholesky 因子是一个下三角矩阵,对角线为正,每行欧几里得范数为 1。变换过程如下

  1. 首先,我们将 x 转换为按行排列的下三角矩阵。

  2. 对于下三角部分的每一行 XiX_i,我们应用一个 带符号的 版本的 StickBreakingTransform 类,使用以下步骤将 XiX_i 转换为单位欧几里德长度的向量: - 缩放至区间 (1,1)(-1, 1) 域: ri=tanh(Xi)r_i = \tanh(X_i). - 转换为无符号域: zi=ri2z_i = r_i^2. - 应用 si=StickBreakingTransform(zi)s_i = StickBreakingTransform(z_i). - 转换回带符号域: yi=sign(ri)siy_i = sign(r_i) * \sqrt{s_i}.

class torch.distributions.transforms.CumulativeDistributionTransform(distribution, cache_size=0)[source]

通过概率分布的累积分布函数进行转换。

参数

distribution (Distribution) – 用于转换的累积分布函数的分布。

示例

# Construct a Gaussian copula from a multivariate normal.
base_dist = MultivariateNormal(
    loc=torch.zeros(2),
    scale_tril=LKJCholesky(2).sample(),
)
transform = CumulativeDistributionTransform(Normal(0, 1))
copula = TransformedDistribution(base_dist, [transform])
class torch.distributions.transforms.ExpTransform(cache_size=0)[source]

通过映射 y=exp(x)y = \exp(x) 进行转换。

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

另一个转换的包装器,将 reinterpreted_batch_ndims 多个最右侧的维度视为依赖的。这对前向或后向转换没有影响,但会在 log_abs_det_jacobian() 中对 reinterpreted_batch_ndims 多个最右侧的维度进行求和。

参数
  • base_transform (Transform) – 基础转换。

  • reinterpreted_batch_ndims (int) – 视为依赖的额外最右侧维度的数量。

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

将无约束矩阵转换为具有非负对角线项的下三角矩阵。

这对于根据其 Cholesky 分解参数化正定矩阵很有用。

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

将无约束矩阵转换为正定矩阵。

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

通过映射 y=xexponenty = x^{\text{exponent}} 进行变换。

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

单位雅可比变换,用于重塑张量的最右边部分。

请注意,in_shapeout_shape 必须具有相同数量的元素,就像 torch.Tensor.reshape() 一样。

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

通过映射 y=11+exp(x)y = \frac{1}{1 + \exp(-x)} 进行变换,以及 x=logit(y)x = \text{logit}(y).

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

通过映射 Softplus(x)=log(1+exp(x))\text{Softplus}(x) = \log(1 + \exp(x)) 进行变换。当 x>20x > 20 时,实现将恢复为线性函数。

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

通过映射 y=tanh(x)y = \tanh(x) 进行变换。

它等效于 ` ComposeTransform([AffineTransform(0., 2.), SigmoidTransform(), AffineTransform(-1., 2.)]) ` 但是这在数值上可能不稳定,因此建议使用 TanhTransform 而不是它。

请注意,在遇到 NaN/Inf 值时,应使用 cache_size=1

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

通过 y=exp(x)y = \exp(x),然后归一化,将无约束空间转换为单纯形。

这不是双射的,不能用于 HMC。但是这在很大程度上是按坐标进行的(除了最终的归一化),因此适合于按坐标进行优化的算法。

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

将一组变换 tseq 按组件方式应用于矩阵中 dim 维度上的每个子矩阵,以与 torch.stack() 兼容的变换函数。

示例

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]

从无约束空间到通过 stick-breaking 过程的 simplex 的一个额外维度的变换。

这种变换在 Dirichlet 分布的 stick-breaking 构造中作为迭代 sigmoid 变换出现:第一个 logit 通过 sigmoid 变换为第一个概率和所有其他概率,然后该过程递归执行。

它是双射的,适合在 HMC 中使用;但是它将坐标混合在一起,不太适合优化。

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

可逆变换的抽象类,具有可计算的对数行列式雅可比矩阵。它们主要用在 torch.distributions.TransformedDistribution 中。

缓存对于逆变换代价高昂或数值不稳定的变换很有用。请注意,必须注意使用记忆的值,因为自动微分图可能会反转。例如,即使以下代码在有或没有缓存的情况下都可以正常工作

y = t(x)
t.log_abs_det_jacobian(x, y).backward()  # x will receive gradients.

但是,当缓存时,由于依赖关系反转,以下代码会出错

y = t(x)
z = t.inv(y)
grad(z.sum(), [y])  # error because z is x

派生类应该实现 _call()_inverse() 中的一个或两个。将 bijective=True 设置为 True 的派生类还应实现 log_abs_det_jacobian()

参数

cache_size (int) – 缓存的大小。如果为零,则不进行缓存。如果为一,则缓存最新的单个值。仅支持 0 和 1。

变量
  • domain (Constraint) – 表示此变换有效输入的约束。

  • codomain (Constraint) – 表示此变换有效输出的约束,这些输出是逆变换的输入。

  • bijective (bool) – 此变换是否为双射。变换 t 为双射当且仅当对于域中的每个 x 和余域中的每个 yt.inv(t(x)) == xt(t.inv(y)) == y 成立。非双射变换至少应保持较弱的伪逆性质 t(t.inv(t(x)) == t(x)t.inv(t(t.inv(y))) == t.inv(y)

  • sign (int or Tensor) – 对于双射单变量变换,这应该为 +1 或 -1,具体取决于变换是单调递增还是递减。

property inv

返回此变换的逆 Transform。这应该满足 t.inv.inv is t

property sign

如果适用,返回雅可比行列式的符号。通常,这仅对双射变换有意义。

log_abs_det_jacobian(x, y)[source]

计算给定输入和输出的对数行列式雅可比矩阵 log |dy/dx|

forward_shape(shape)[source]

推断给定输入形状的正向计算的形状。默认情况下保留形状。

inverse_shape(shape)[source]

推断给定输出形状的逆计算的形状。默认情况下保留形状。

Constraints

实现了以下约束

  • constraints.boolean

  • constraints.cat

  • constraints.corr_cholesky

  • constraints.dependent

  • constraints.greater_than(lower_bound)

  • constraints.greater_than_eq(lower_bound)

  • constraints.independent(constraint, reinterpreted_batch_ndims)

  • constraints.integer_interval(lower_bound, upper_bound)

  • constraints.interval(lower_bound, upper_bound)

  • constraints.less_than(upper_bound)

  • constraints.lower_cholesky

  • constraints.lower_triangular

  • constraints.multinomial

  • constraints.nonnegative

  • constraints.nonnegative_integer

  • constraints.one_hot

  • constraints.positive_integer

  • constraints.positive

  • constraints.positive_semidefinite

  • constraints.positive_definite

  • constraints.real_vector

  • constraints.real

  • constraints.simplex

  • constraints.symmetric

  • constraints.stack

  • constraints.square

  • constraints.symmetric

  • constraints.unit_interval

class torch.distributions.constraints.Constraint[source]

约束的抽象基类。

约束对象表示变量有效的区域,例如,变量可以在其中进行优化。

变量
  • is_discrete (bool) – 约束空间是否为离散的。默认为 False。

  • event_dim (int) – 一起定义事件的最右边维度的数量。在计算有效性时,check() 方法将删除这些维度的数量。

check(value)[source]

返回一个 sample_shape + batch_shape 的字节张量,指示 value 中的每个事件是否满足此约束。

torch.distributions.constraints.cat

_Cat 的别名

torch.distributions.constraints.dependent_property

_DependentProperty 的别名

torch.distributions.constraints.greater_than

_GreaterThan 的别名

torch.distributions.constraints.greater_than_eq

_GreaterThanEq 的别名

torch.distributions.constraints.independent

_IndependentConstraint 的别名

torch.distributions.constraints.integer_interval

_IntegerInterval 的别名

torch.distributions.constraints.interval

_Interval 的别名

torch.distributions.constraints.half_open_interval

_HalfOpenInterval 的别名

torch.distributions.constraints.less_than

_LessThan 的别名

torch.distributions.constraints.multinomial

_Multinomial 的别名

torch.distributions.constraints.stack

_Stack 的别名

Constraint Registry

PyTorch 提供两个全局 ConstraintRegistry 对象,它们将 Constraint 对象链接到 Transform 对象。这两个对象都接受约束并返回变换,但它们在双射性方面有不同的保证。

  1. biject_to(constraint) 查找一个从 constraints.real 到给定 constraint 的双射 Transform。返回的变换保证具有 .bijective = True,并且应该实现 .log_abs_det_jacobian()

  2. transform_to(constraint) 查找一个从 constraints.real 到给定 constraint 的不一定双射的 Transform。返回的变换不保证实现 .log_abs_det_jacobian()

transform_to() 注册表对于对概率分布的约束参数执行无约束优化很有用,这些参数由每个分布的 .arg_constraints 字典指示。这些变换通常会过度参数化一个空间以避免旋转;因此,它们更适合于像 Adam 这样的逐坐标优化算法。

loc = torch.zeros(100, requires_grad=True)
unconstrained = torch.zeros(100, requires_grad=True)
scale = transform_to(Normal.arg_constraints['scale'])(unconstrained)
loss = -Normal(loc, scale).log_prob(data).sum()

biject_to() 注册表对于哈密顿蒙特卡罗很有用,其中来自具有约束 .support 的概率分布的样本在无约束空间中传播,并且算法通常是旋转不变的。

dist = Exponential(rate)
unconstrained = torch.zeros(100, requires_grad=True)
sample = biject_to(dist.support)(unconstrained)
potential_energy = -dist.log_prob(sample).sum()

注意

transform_tobiject_to 不同的一个例子是 constraints.simplextransform_to(constraints.simplex) 返回一个 SoftmaxTransform,它只对输入进行指数运算并进行归一化;这是一个廉价的,主要是逐坐标的操作,适合像 SVI 这样的算法。相反,biject_to(constraints.simplex) 返回一个 StickBreakingTransform,它将输入双射到一个少一个维度的空间中;这是一个更昂贵的,数值上更不稳定的变换,但对于像 HMC 这样的算法是必要的。

biject_totransform_to 对象可以通过用户定义的约束和变换使用它们的 .register() 方法来扩展,无论是作为单例约束上的函数

transform_to.register(my_constraint, my_transform)

还是作为参数化约束上的装饰器

@transform_to.register(MyConstraintClass)
def my_factory(constraint):
    assert isinstance(constraint, MyConstraintClass)
    return MyTransform(constraint.param1, constraint.param2)

你可以通过创建一个新的 ConstraintRegistry 对象来创建自己的注册表。

class torch.distributions.constraint_registry.ConstraintRegistry[source]

将约束链接到变换的注册表。

register(constraint, factory=None)[source]

在这个注册表中注册一个 Constraint 子类。用法

@my_registry.register(MyConstraintClass)
def construct_transform(constraint):
    assert isinstance(constraint, MyConstraint)
    return MyTransform(constraint.arg_constraints)
参数
  • constraint (subclass of Constraint) – Constraint 的子类,或所需类的单例对象。

  • factory (Callable) – 一个可调用对象,它接受一个约束对象并返回一个 Transform 对象。

文档

访问 PyTorch 的全面开发者文档

查看文档

教程

获得针对初学者和高级开发者的深入教程

查看教程

资源

查找开发资源并获得问题的解答

查看资源