概率分布 - torch.distributions

创建日期：2017 年 10 月 19 日 | 最后更新日期：2025 年 6 月 13 日

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

无法直接通过随机采样进行反向传播。然而，有两种主要方法可以创建可以反向传播的代理函数。它们是得分函数估计器/似然比估计器/REINFORCE 和路径导数估计器。REINFORCE 通常被视为强化学习中策略梯度方法的基础，而路径导数估计器通常在变分自编码器的重参数化技巧中出现。虽然得分函数只需要样本 $f(x)$ 的值，但路径导数需要导数 $f'(x)$. 下面的章节将在强化学习示例中讨论这两种方法。更多详细信息请参阅 使用随机计算图进行梯度估计 。

得分函数

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

$$\Delta\theta = \alpha r \frac{\partial\log p(a|\pi^\theta(s))}{\partial\theta}$$

其中 $\theta$ 是参数，$\alpha$ 是学习率，$r$ 是奖励，$p(a|\pi^\theta(s))$ 是在状态 $s$ 下，给定策略 $\pi^\theta$ 下采取动作 $a$ 的概率。

在实践中，我们将从网络的输出中采样一个动作，在环境中应用该动作，然后使用 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()

隐藏节Distribution

class torch.distributions.distribution.Distribution(batch_shape=(), event_shape=(), validate_args=None)

基类： object

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

参数:

• batch_shape (torch.Size) – 参数进行批处理的形状。

• event_shape (torch.Size) – 单个样本的形状（不包含批处理）。

• validate_args (bool, optional) – 是否验证参数。默认为 None。

property arg_constraints: dict[str, Constraint]

返回一个字典，将参数名映射到 Constraint 对象，这些对象应该由该分布的每个参数满足。不是张量的参数无需出现在此字典中。

property batch_shape: Size

返回参数进行批处理的形状。

cdf(value)

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

参数:

value (Tensor) –

返回类型:

张量

entropy()

返回分布的熵，按 batch_shape 进行批处理。

返回:

形状为 batch_shape 的张量。

返回类型:

张量

enumerate_support(expand=True)

返回包含离散分布所有支持值的张量。结果将枚举维度 0，因此结果的形状为 (基数,) + 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 进行枚举的张量。

返回类型:

张量

property event_shape: Size

返回单个样本的形状（不包含批处理）。

expand(batch_shape, _instance=None)

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

参数:

• batch_shape (torch.Size) – 所需的扩展大小。

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

返回:

批次维度已扩展到 batch_size 的新分布实例。

icdf(value)

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

参数:

value (Tensor) –

返回类型:

张量

log_prob(value)

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

参数:

value (Tensor) –

返回类型:

张量

property mean: Tensor

返回分布的均值。

property mode: Tensor

返回分布的众数。

perplexity()

返回分布的困惑度，按 batch_shape 进行批处理。

返回:

形状为 batch_shape 的张量。

返回类型:

张量

rsample(sample_shape=())

生成 sample_shape 形状的重参数化样本，如果分布参数是批处理的，则生成 sample_shape 形状的重参数化样本批次。

返回类型:

张量

sample(sample_shape=())

生成 sample_shape 形状的样本，如果分布参数是批处理的，则生成 sample_shape 形状的样本批次。

返回类型:

张量

sample_n(n)

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

返回类型:

张量

static set_default_validate_args(value)

设置验证是启用还是禁用。

默认行为模仿 Python 的 assert 语句：验证默认开启，但在 Python 以优化模式（通过 python -O）运行时禁用。验证可能很耗时，因此您可能希望在模型工作正常后禁用它。

参数:

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

property stddev: Tensor

返回分布的标准差。

property support: Constraint | None

返回一个 Constraint 对象，表示此分布的支持集。

property variance: Tensor

返回分布的方差。

隐藏节ExponentialFamily

class torch.distributions.exp_family.ExponentialFamily(batch_shape=(), event_shape=(), validate_args=None)

基类： Distribution

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

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

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

注意

此类是 Distribution 类与属于指数族的分布之间的中间类，主要是为了检查 .entropy() 和解析 KL 散度方法的正确性。我们使用此类通过 AD 框架和 Bregman 散度（来源：Frank Nielsen 和 Richard Nock，指数族的熵和交叉熵）来计算熵和 KL 散度。

entropy()

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

隐藏节Bernoulli

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

基类： ExponentialFamily

使用 probs 或 logits（但不能同时）参数化的伯努利分布。

样本是二元的（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 的对数几率

• validate_args (bool, optional) – 是否验证参数，默认为 None

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

entropy()

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

has_enumerate_support = True

log_prob(value)

property logits: Tensor

property mean: Tensor

property mode: Tensor

property param_shape: Size

属性 probs: 张量

sample(sample_shape=())

support = Boolean()

属性 variance: 张量

Beta

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

基类： ExponentialFamily

由 concentration1 和 concentration0 参数化的 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 或 张量) – 分布的第一个浓度参数（通常称为 alpha）

• concentration0 (float 或 张量) – 分布的第二个浓度参数（通常称为 beta）

arg_constraints = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0)}

属性 concentration0: 张量

属性 concentration1: 张量

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

属性 mean: 张量

属性 mode: 张量

rsample(sample_shape=())

返回类型:

张量

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

属性 variance: 张量

Binomial

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

基类： Distribution

创建一个由 total_count 和 probs 或 logits（但不能同时）参数化的二项分布。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 或 张量) – Bernoulli 试验次数

• probs (张量) – 事件概率

• logits (张量) – 事件对数几率

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

entropy()

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

has_enumerate_support = True

log_prob(value)

属性 logits: 张量

属性 mean: 张量

属性 mode: 张量

属性 param_shape: Size

属性 probs: 张量

sample(sample_shape=())

属性 support

返回类型:

_DependentProperty

属性 variance: 张量

Categorical

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

基类： Distribution

创建一个由 probs 或 logits（但不能同时）参数化的分类分布。

注意

它等同于 torch.multinomial() 采样的分布。

样本是从 $\{0, \ldots, K-1\}$ 中的整数，其中 K 是 probs.size(-1)。

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

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

注意

The probs 参数必须是非负的、有限的，并且具有非零和，它将在最后一个维度上被归一化以求和为 1。probs 将返回此归一化值。The logits 参数将被解释为未归一化的对数概率，因此可以是任何实数。它也将被归一化，以便生成的概率在最后一个维度上求和为 1。logits 将返回此归一化值。

另请参阅： torch.multinomial()

示例

>>> m = Categorical(torch.tensor([ 0.25, 0.25, 0.25, 0.25 ]))
>>> m.sample()  # equal probability of 0, 1, 2, 3
tensor(3)

参数:

• probs (张量) – 事件概率

• logits (张量) – 事件对数概率（未归一化）

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

entropy()

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

has_enumerate_support = True

log_prob(value)

属性 logits: 张量

属性 mean: 张量

属性 mode: 张量

属性 param_shape: Size

属性 probs: 张量

sample(sample_shape=())

属性 support

返回类型:

_DependentProperty

属性 variance: 张量

Cauchy

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

基类： 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])

参数:

• loc (float 或 张量) – 分布的众数或中位数。

• scale (float 或 张量) – 半高宽。

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

属性 mean: 张量

属性 mode: 张量

rsample(sample_shape=())

返回类型:

张量

support = Real()

属性 variance: 张量

Chi2

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

Bases: 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 (float 或 Tensor) – 分布的形状参数

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

property df: Tensor

expand(batch_shape, _instance=None)

ContinuousBernoulli

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

基类： ExponentialFamily

创建由 probs 或 logits (但不能同时) 参数化的连续伯努利分布。

该分布支持 [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) – 匹配“probs”的实值参数

[1] Loaiza-Ganem G 和 Cunningham JP, NeurIPS 2019 的论文《The continuous Bernoulli: fixing a pervasive error in variational autoencoders》。 https://arxiv.org/abs/1907.06845

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

property logits: Tensor

property mean: Tensor

property param_shape: Size

property probs: Tensor

rsample(sample_shape=())

返回类型:

张量

sample(sample_shape=())

property stddev: Tensor

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

property variance: Tensor

Dirichlet

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

基类： 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()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

support = Simplex()

property variance: Tensor

Exponential

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

基类： ExponentialFamily

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

示例

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

参数:

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

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

property stddev: Tensor

support = GreaterThanEq(lower_bound=0.0)

property variance: Tensor

FisherSnedecor

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

基类： Distribution

创建由 df1 和 df2 参数化的 Fisher-Snedecor 分布。

示例

>>> m = FisherSnedecor(torch.tensor([1.0]), torch.tensor([2.0]))
>>> m.sample()  # Fisher-Snedecor-distributed with df1=1 and df2=2
tensor([ 0.2453])

参数:

• df1 (float 或 Tensor) – 参数 1 的自由度

• df2 (float 或 Tensor) – 参数 2 的自由度

arg_constraints = {'df1': GreaterThan(lower_bound=0.0), 'df2': GreaterThan(lower_bound=0.0)}

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

support = GreaterThan(lower_bound=0.0)

property variance: Tensor

Gamma

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

基类： ExponentialFamily

创建由形状 concentration 和 rate 参数化的 Gamma 分布。

示例

>>> 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 或 Tensor) – 分布的形状参数（通常称为 alpha）

• rate (float 或 Tensor) – 分布的 rate 参数（通常称为 beta），rate = 1 / scale

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

support = GreaterThanEq(lower_bound=0.0)

property variance: Tensor

GeneralizedPareto

class torch.distributions.generalized_pareto.GeneralizedPareto(loc, scale, concentration, validate_args=None)

基类： Distribution

创建由 loc、scale 和 concentration 参数化的广义帕累托分布。

广义帕累托分布是一族定义在实数轴上的连续概率分布。特殊情况包括指数分布（当 loc = 0，concentration = 0 时）、帕累托分布（当 concentration > 0，loc = scale / concentration 时）和均匀分布（当 concentration = -1 时）。

该分布常用于对其他分布的尾部进行建模。此实现基于 TensorFlow Probability 中的实现。

示例

>>> m = GeneralizedPareto(torch.tensor([0.1]), torch.tensor([2.0]), torch.tensor([0.4]))
>>> m.sample()  # sample from a Generalized Pareto distribution with loc=0.1, scale=2.0, and concentration=0.4
tensor([ 1.5623])

参数:

• loc (float 或 Tensor) – 分布的位置参数

• scale (float 或 Tensor) – 分布的 scale 参数

• concentration (float 或 Tensor) – 分布的浓度参数

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_cdf(value)

log_prob(value)

log_survival_function(value)

property mean

property mode

rsample(sample_shape=())

property support

返回类型:

_DependentProperty

property variance

Geometric

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

基类： Distribution

创建一个由 probs 参数化的 Geometric 分布，其中 probs 是 Bernoulli 试验成功的概率。

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

注意

torch.distributions.geometric.Geometric() $(k+1)$ 次试验是第一次成功，因此样本在 $\{0, 1, \ldots\}$ 中，而 torch.Tensor.geometric_() 的 k 次试验是第一次成功，因此样本在 $\{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 的对数几率。

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

entropy()

expand(batch_shape, _instance=None)

log_prob(value)

property logits: Tensor

property mean: Tensor

property mode: Tensor

property probs: Tensor

sample(sample_shape=())

support = IntegerGreaterThan(lower_bound=0)

property variance: Tensor

Gumbel

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

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

参数:

• loc (float 或 Tensor) – 分布的位置参数

• scale (float 或 Tensor) – 分布的 scale 参数

arg_constraints: dict[str, Constraint] = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

entropy()

expand(batch_shape, _instance=None)

log_prob(value)

property mean: Tensor

property mode: Tensor

property stddev: Tensor

support = Real()

property variance: Tensor

HalfCauchy

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

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 或 Tensor) – 完整柯西分布的尺度

arg_constraints: dict[str, Constraint] = {'scale': GreaterThan(lower_bound=0.0)}

base_dist: Cauchy

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(prob)

log_prob(value)

property mean: Tensor

property mode: Tensor

property scale: Tensor

support = GreaterThanEq(lower_bound=0.0)

property variance: Tensor

HalfNormal

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

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 或 Tensor) – 完整正态分布的尺度

arg_constraints: dict[str, Constraint] = {'scale': GreaterThan(lower_bound=0.0)}

base_dist: Normal

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(prob)

log_prob(value)

property mean: Tensor

property mode: Tensor

property scale: Tensor

support = GreaterThanEq(lower_bound=0.0)

property variance: Tensor

Independent

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

Bases: Distribution, Generic[D]

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

这主要用于更改 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])]

参数:

• base_distribution (torch.distributions.distribution.Distribution) – 一个基础分布

• reinterpreted_batch_ndims (int) – 要重新解释为事件维度的批次维度数量

arg_constraints: dict[str, Constraint] = {}

base_dist: D

entropy()

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

property has_enumerate_support: bool

property has_rsample: bool

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

sample(sample_shape=())

返回类型:

张量

property support

返回类型:

_DependentProperty

property variance: Tensor

InverseGamma

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

Bases: TransformedDistribution

创建一个逆伽马分布，由 concentration 和 rate 参数化，其中

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 或 Tensor) – 分布的形状参数（通常称为 alpha）

• rate (float 或 Tensor) – rate = 1 / scale of the distribution (通常称为 beta)

arg_constraints: dict[str, Constraint] = {'concentration': GreaterThan(lower_bound=0.0), 'rate': GreaterThan(lower_bound=0.0)}

base_dist: Gamma

property concentration: Tensor

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

property mean: Tensor

property mode: Tensor

property rate: Tensor

support = GreaterThan(lower_bound=0.0)

property variance: Tensor

Kumaraswamy

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

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 或 张量) – 分布的第一个浓度参数（通常称为 alpha）

• concentration0 (float 或 张量) – 分布的第二个浓度参数（通常称为 beta）

arg_constraints: dict[str, Constraint] = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0)}

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

property mean: Tensor

property mode: Tensor

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

property variance: Tensor

LKJCholesky

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

基类： Distribution

用于相关矩阵的低三角 Cholesky 因子。该分布由 concentration 参数 $\eta$ 控制，使得从 Cholesky 因子生成的协方差矩阵 $M$ 的概率与 $\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]])

参数:

• dimension (dim) – 矩阵的维度

• concentration (float 或 Tensor) – 分布的 concentration/shape 参数 (通常称为 eta)

参考文献

[1] Generating random correlation matrices based on vines and extended onion method (2009), Daniel Lewandowski, Dorota Kurowicka, Harry Joe. Journal of Multivariate Analysis. 100. 10.1016/j.jmva.2009.04.008

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

expand(batch_shape, _instance=None)

log_prob(value)

sample(sample_shape=())

support = CorrCholesky()

Laplace

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

基类： Distribution

使用 loc 和 scale 参数化创建拉普拉斯分布。

示例

>>> m = Laplace(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # Laplace distributed with loc=0, scale=1
tensor([ 0.1046])

参数:

• loc (float 或 Tensor) – 分布的均值

• scale (float 或 Tensor) – 分布的 scale

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

property stddev: Tensor

support = Real()

property variance: Tensor

LogNormal

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

Bases: TransformedDistribution

创建一个由 loc 和 scale 参数化的对数正态分布，其中

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

参数:

• loc (float 或 Tensor) – distribution of log 的均值

• scale (float 或 Tensor) – distribution of log 的标准差

arg_constraints: dict[str, Constraint] = {'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

base_dist: Normal

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

property loc: Tensor

property mean: Tensor

property mode: Tensor

property scale: Tensor

support = GreaterThan(lower_bound=0.0)

property variance: Tensor

LowRankMultivariateNormal

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

基类： Distribution

创建一个协方差矩阵具有低秩形式的多元正态分布，由 cov_factor 和 cov_diag 参数化。

covariance_matrix = cov_factor @ cov_factor.T + cov_diag

示例

>>> m = LowRankMultivariateNormal(
...     torch.zeros(2), torch.tensor([[1.0], [0.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

注意

由于 Woodbury 矩阵恒等式 和 矩阵行列式引理，避免了协方差矩阵的行列式和逆的计算，当 cov_factor.shape[1] << cov_factor.shape[0] 时。通过这些公式，我们只需要计算小型“电容”矩阵的行列式和逆。

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

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

property precision_matrix: Tensor

rsample(sample_shape=())

返回类型:

张量

property scale_tril: Tensor

support = IndependentConstraint(Real(), 1)

property variance: Tensor

MixtureSameFamily

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

基类： 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_distribution (Categorical) – 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 (Distribution) – torch.distributions.Distribution-like instance. Right-most batch dimension indexes component。

arg_constraints: dict[str, Constraint] = {}

cdf(x)

property component_distribution: Distribution

expand(batch_shape, _instance=None)

has_rsample = False

log_prob(x)

property mean: Tensor

property mixture_distribution: Categorical

sample(sample_shape=())

property support

返回类型:

_DependentProperty

property variance: Tensor

Multinomial

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

基类： 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 (张量) – 事件概率

• logits (张量) – 事件对数概率（未归一化）

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

entropy()

expand(batch_shape, _instance=None)

log_prob(value)

property logits: Tensor

property mean: Tensor

property param_shape: Size

property probs: Tensor

sample(sample_shape=())

property support

返回类型:

_DependentProperty

total_count: int

property variance: Tensor

MultivariateNormal

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

基类： 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 $\mathbf{\Sigma}^{-1}$ or a lower-triangular matrix $\mathbf{L}$ with positive-valued diagonal entries, such that $\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top$. This triangular matrix can be obtained via e.g. Cholesky decomposition of the covariance。

示例

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

注意

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

property covariance_matrix: Tensor

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

property precision_matrix: Tensor

rsample(sample_shape=())

返回类型:

张量

property scale_tril: Tensor

support = IndependentConstraint(Real(), 1)

property variance: Tensor

NegativeBinomial

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

基类： 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 success of each Bernoulli trial is probs。

参数:

• 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 success in the half open interval [0, 1)

• logits (Tensor) – Event log-odds for probabilities of success

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)

log_prob(value)

property logits: Tensor

property mean: Tensor

property mode: Tensor

property param_shape: Size

property probs: Tensor

sample(sample_shape=())

support = IntegerGreaterThan(lower_bound=0)

property variance: Tensor

Normal

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

基类： ExponentialFamily

创建一个由 loc 和 scale 参数化的正态（也称为高斯）分布。

示例

>>> m = Normal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # normally distributed with loc=0 and scale=1
tensor([ 0.1046])

参数:

• loc (float 或 Tensor) – 分布的均值（通常称为 mu）

• scale (float 或 Tensor) – 分布的标准差（通常称为 sigma）

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

sample(sample_shape=())

property stddev: Tensor

support = Real()

property variance: Tensor

OneHotCategorical

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

基类： Distribution

创建一个由 probs 或 logits 参数化的 one-hot 类别分布。

样本是大小为 probs.size(-1) 的 one-hot 编码向量。

注意

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

另请参阅： torch.distributions.Categorical()，了解 probs 和 logits 的规范。

示例

>>> 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 (张量) – 事件概率

• logits (张量) – 事件对数概率（未归一化）

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

entropy()

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

has_enumerate_support = True

log_prob(value)

property logits: Tensor

property mean: Tensor

property mode: Tensor

property param_shape: Size

property probs: Tensor

sample(sample_shape=())

support = OneHot()

property variance: Tensor

Pareto

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

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

参数:

• scale (float 或 Tensor) – 分布的 scale 参数

• alpha (float 或 Tensor) – 分布的形状参数

arg_constraints: dict[str, Constraint] = {'alpha': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}

entropy()

返回类型:

张量

expand(batch_shape, _instance=None)

返回类型:

Pareto

property mean: Tensor

property mode: Tensor

property support: Constraint

返回类型:

_DependentProperty

property variance: Tensor

Poisson

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

基类： ExponentialFamily

创建一个由 rate（速率参数）参数化的泊松分布。

样本是非负整数，其概率质量函数 (pmf) 给出为：

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

示例

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

参数:

rate (Number, Tensor) – 速率参数

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

expand(batch_shape, _instance=None)

log_prob(value)

property mean: Tensor

property mode: Tensor

sample(sample_shape=())

support = IntegerGreaterThan(lower_bound=0)

property variance: Tensor

RelaxedBernoulli

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

Bases: TransformedDistribution

创建一个 RelaxedBernoulli 分布，该分布由 temperature 以及 probs 或 logits（但不能同时两者）参数化。这是 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)}

base_dist: LogitRelaxedBernoulli

expand(batch_shape, _instance=None)

has_rsample = True

property logits: Tensor

property probs: Tensor

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

property temperature: Tensor

LogitRelaxedBernoulli

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

基类： Distribution

创建一个由 probs 或 logits (但不能两者都提供) 参数化的 LogitRelaxedBernoulli 分布，它是 RelaxedBernoulli 分布的 logit。

样本是 (0, 1) 中的值的 logits。更多细节请参阅 [1]。

参数:

• temperature (Tensor) – 松弛温度

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

• logits (Number, Tensor) – 采样 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)

log_prob(value)

property logits: Tensor

property param_shape: Size

property probs: Tensor

rsample(sample_shape=())

返回类型:

张量

support = Real()

RelaxedOneHotCategorical

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

Bases: TransformedDistribution

使用 temperature 以及 probs 或 logits 参数化的 RelaxedOneHotCategorical 分布。这是 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 (张量) – 事件概率

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

arg_constraints: dict[str, Constraint] = {'logits': IndependentConstraint(Real(), 1), 'probs': Simplex()}

base_dist: ExpRelaxedCategorical

expand(batch_shape, _instance=None)

has_rsample = True

property logits: Tensor

property probs: Tensor

support = Simplex()

property temperature: Tensor

StudentT

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

基类： Distribution

创建一个由自由度 df、均值 loc 和尺度 scale 参数化的 Student's t 分布。

示例

>>> m = StudentT(torch.tensor([2.0]))
>>> m.sample()  # Student's t-distributed with degrees of freedom=2
tensor([ 0.1046])

参数:

• df (float 或 Tensor) – 自由度

• loc (float 或 Tensor) – 分布的均值

• scale (float 或 Tensor) – 分布的 scale

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

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

support = Real()

property variance: Tensor

TransformedDistribution

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

基类： Distribution

扩展了 Distribution 类，该类将一系列 Transform 应用于基本分布。令 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)

有关更多示例，请参阅 Gumbel、HalfCauchy、HalfNormal、LogNormal、Pareto、Weibull、RelaxedBernoulli 和 RelaxedOneHotCategorical 的实现。

arg_constraints: dict[str, Constraint] = {}

cdf(value)

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

expand(batch_shape, _instance=None)

property has_rsample: bool

icdf(value)

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

log_prob(value)

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

rsample(sample_shape=())

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

返回类型:

张量

sample(sample_shape=())

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

property support

返回类型:

_DependentProperty

Uniform

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

基类： 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 或 Tensor) – 下界（包含）。

• high (float 或 Tensor) – 上界（不包含）。

property arg_constraints

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

property mean: Tensor

property mode: Tensor

rsample(sample_shape=())

返回类型:

张量

property stddev: Tensor

property support

返回类型:

_DependentProperty

property variance: Tensor

VonMises

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

基类： Distribution

一个圆 von Mises 分布。

此实现使用极坐标。 loc 和 value 参数可以是任何实数（以方便无约束优化），但被解释为模 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])

参数:

• loc (torch.Tensor) – 以弧度为单位的角度。

• concentration (torch.Tensor) – 集中度参数

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

expand(batch_shape, _instance=None)

has_rsample = False

log_prob(value)

property mean: Tensor

提供的均值是圆均值。

property mode: Tensor

sample(sample_shape=())

von Mises 分布的采样算法基于以下论文：D.J. Best 和 N.I. Fisher，“Efficient simulation of the von Mises distribution。” Applied Statistics (1979)：152-157。

采样始终在内部以双精度进行，以避免在浓度值很小时在 _rejection_sample() 中出现挂起，这种情况在单精度下大约在 1e-4 时开始发生（参见 issue #88443）。

support = Real()

property variance: Tensor

提供的方差是圆的方差。

Weibull

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

Bases: TransformedDistribution

从双参数 Weibull 分布进行采样。

示例

>>> 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 (float 或 Tensor) – 分布的尺度参数 (lambda)。

• concentration (float 或 Tensor) – 分布的集中度参数 (k/shape)。

• validate_args (bool, optional) – 是否验证参数。默认为 None。

arg_constraints: dict[str, Constraint] = {'concentration': GreaterThan(lower_bound=0.0), 'scale': GreaterThan(lower_bound=0.0)}

entropy()

expand(batch_shape, _instance=None)

property mean: Tensor

property mode: Tensor

support = GreaterThan(lower_bound=0.0)

property variance: Tensor

Wishart

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

基类： ExponentialFamily

创建一个 Wishart 分布，由对称正定矩阵 $\Sigma$ 或其 Cholesky 分解 $\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 (float 或 Tensor) – 实值参数，大于 (方阵的维度) - 1

• 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

注意

只能指定 covariance_matrix、precision_matrix 或 scale_tril 中的一个。使用 scale_tril 会更有效：所有内部计算都基于 scale_tril。如果改为传入 covariance_matrix 或 precision_matrix，则仅用于通过 Cholesky 分解计算相应的下三角矩阵。'torch.distributions.LKJCholesky' 是一个受限的 Wishart 分布。[1]

参考文献

[1] Wang, Z., Wu, Y. and Chu, H., 2018. On equivalence of the LKJ distribution and the restricted Wishart distribution. [2] Sawyer, S., 2007. Wishart Distributions and Inverse-Wishart Sampling. [3] Anderson, T. W., 2003. An Introduction to Multivariate Statistical Analysis (3rd ed.). [4] Odell, P. L. & Feiveson, A. H., 1966. A Numerical Procedure to Generate a SampleCovariance Matrix. JASA, 61(313):199-203. [5] Ku, Y.-C. & Bloomfield, P., 2010. Generating Random Wishart Matrices with Fractional Degrees of Freedom in OX.

property arg_constraints

property covariance_matrix: Tensor

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean: Tensor

property mode: Tensor

property precision_matrix: Tensor

rsample(sample_shape=(), max_try_correction=None)

警告

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

返回类型:

张量

property scale_tril: Tensor

support = PositiveDefinite()

property variance: Tensor

KL Divergence

torch.distributions.kl.kl_divergence(p, q)

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

$$KL(p \| q) = \int p(x) \log\frac {p(x)} {q(x)} \,dx$$

参数:

• p (Distribution) – 一个 Distribution 对象。

• q (Distribution) – 一个 Distribution 对象。

返回:

形状为 batch_shape 的 KL 散度批。

返回类型:

张量

抛出:

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

KL 散度目前已为以下分布对实现：

• Bernoulli 和 Bernoulli

• Bernoulli 和 Poisson

• Beta 和 Beta

• Beta 和 ContinuousBernoulli

• Beta 和 Exponential

• Beta 和 Gamma

• Beta 和 Normal

• Beta 和 Pareto

• Beta 和 Uniform

• Binomial 和 Binomial

• Categorical 和 Categorical

• Cauchy 和 Cauchy

• ContinuousBernoulli 和 ContinuousBernoulli

• ContinuousBernoulli 和 Exponential

• ContinuousBernoulli 和 Normal

• ContinuousBernoulli 和 Pareto

• ContinuousBernoulli 和 Uniform

• Dirichlet 和 Dirichlet

• Exponential 和 Beta

• Exponential 和 ContinuousBernoulli

• Exponential 和 Exponential

• Exponential 和 Gamma

• Exponential 和 Gumbel

• Exponential 和 Normal

• Exponential 和 Pareto

• Exponential 和 Uniform

• ExponentialFamily 和 ExponentialFamily

• Gamma 和 Beta

• Gamma 和 ContinuousBernoulli

• Gamma 和 Exponential

• Gamma 和 Gamma

• Gamma 和 Gumbel

• Gamma 和 Normal

• Gamma 和 Pareto

• Gamma 和 Uniform

• Geometric 和 Geometric

• Gumbel 和 Beta

• Gumbel 和 ContinuousBernoulli

• Gumbel 和 Exponential

• Gumbel 和 Gamma

• Gumbel 和 Gumbel

• Gumbel 和 Normal

• Gumbel 和 Pareto

• Gumbel 和 Uniform

• HalfNormal 和 HalfNormal

• Independent 和 Independent

• Laplace 和 Beta

• Laplace 和 ContinuousBernoulli

• Laplace 和 Exponential

• Laplace 和 Gamma

• Laplace 和 Laplace

• Laplace 和 Normal

• Laplace 和 Pareto

• Laplace 和 Uniform

• LowRankMultivariateNormal 和 LowRankMultivariateNormal

• LowRankMultivariateNormal 和 MultivariateNormal

• MultivariateNormal 和 LowRankMultivariateNormal

• MultivariateNormal 和 MultivariateNormal

• Normal 和 Beta

• Normal 和 ContinuousBernoulli

• 正态分布 and 指数分布

• 正态分布 and Gamma分布

• 正态分布 and Gumbel分布

• 正态分布 and Laplace分布

• 正态分布 and 正态分布

• 正态分布 and Pareto分布

• 正态分布 and 均匀分布

• OneHotCategorical分布 and OneHotCategorical分布

• Pareto分布 and Beta分布

• Pareto分布 and ContinuousBernoulli分布

• Pareto分布 and 指数分布

• Pareto分布 and Gamma分布

• Pareto分布 and 正态分布

• Pareto分布 and Pareto分布

• Pareto分布 and 均匀分布

• Poisson分布 and Bernoulli分布

• Poisson分布 and Binomial分布

• Poisson分布 and Poisson分布

• TransformedDistribution and TransformedDistribution

• 均匀分布 and Beta分布

• 均匀分布 and ContinuousBernoulli分布

• 均匀分布 and 指数分布

• 均匀分布 and Gamma分布

• 均匀分布 and Gumbel分布

• 均匀分布 and 正态分布

• 均匀分布 and Pareto分布

• 均匀分布 and 均匀分布

torch.distributions.kl.register_kl(type_p, type_q)

装饰器，用于向 kl_divergence() 注册成对函数。用法

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

查找返回最具体的 (type,type) 匹配项，按子类排序。如果匹配不明确，则引发 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 的子类。

变换

class torch.distributions.transforms.AbsTransform(cache_size=0)

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

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

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

参数:

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

• scale (Tensor 或 float) – 缩放参数。

• event_dim (int) – event_shape 的可选大小。对于一元随机变量应为零，对于向量上的分布应为 1，对于矩阵上的分布应为 2，依此类推。

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

变换函子，它沿着 dim 处每个子矩阵（长度为 lengths[dim]）分量式地应用一系列变换 tseq，方式与 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)

将多个变换串联起来。被组合的变换负责缓存。

参数:

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

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

class torch.distributions.transforms.CorrCholeskyTransform(cache_size=0)

将长度为 $D*(D-1)/2$ 的未约束实数向量 $x$ 转换为 D 维相关矩阵的 Cholesky 因子。该 Cholesky 因子是一个下三角矩阵，其对角线元素为正，每行的欧几里得范数为 1。变换的处理步骤如下：

1. 首先，我们将 x 按行顺序转换为下三角矩阵。

2. 对于下三角部分的每一行 $X_i$，我们应用 StickBreakingTransform 的有符号版本，通过以下步骤将 $X_i$ 转换为欧几里得范数为 1 的向量： - 缩放到区间 $(-1, 1)$ 域： $r_i = \tanh(X_i)$. - 转换为无符号域： $z_i = r_i^2$. - 应用 $s_i = StickBreakingTransform(z_i)$. - 转换回有符号域： $y_i = sign(r_i) * \sqrt{s_i}$.

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

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

参数:

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)

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

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

另一个变换的包装器，用于将 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)

将未约束矩阵转换为对角线元素为非负的下三角矩阵的变换。

这在根据其 Cholesky 分解对正定矩阵进行参数化时很有用。

class torch.distributions.transforms.PositiveDefiniteTransform(cache_size=0)

将非约束矩阵转换为正定矩阵的变换。

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

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

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

将张量的最右边部分重塑为单位雅可比变换。

请注意，与 torch.Tensor.reshape() 一样，in_shape 和 out_shape 必须具有相同数量的元素。

参数:

• in_shape (torch.Size) – 输入事件形状。

• out_shape (torch.Size) – 输出事件形状。

• cache_size (int) – 缓存大小。如果为零，则不进行缓存。如果为一，则缓存最新的单个值。只支持 0 和 1。（默认为 0。）

class torch.distributions.transforms.SigmoidTransform(cache_size=0)

通过映射 $y = \frac{1}{1 + \exp(-x)}$和 $x = \text{logit}(y)$ 进行变换。

class torch.distributions.transforms.SoftplusTransform(cache_size=0)

通过映射 $\text{Softplus}(x) = \log(1 + \exp(x))$ 进行变换。当 $x > 20$ 时，实现会回退到线性函数。

class torch.distributions.transforms.TanhTransform(cache_size=0)

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

这等同于

ComposeTransform(
    [
        AffineTransform(0.0, 2.0),
        SigmoidTransform(),
        AffineTransform(-1.0, 2.0),
    ]
)

但是这可能不够稳定，因此建议使用 TanhTransform 代替。

请注意，在处理 NaN/Inf 值时，应使用 cache_size=1。

class torch.distributions.transforms.SoftmaxTransform(cache_size=0)

通过 $y = \exp(x)$ 然后归一化，将非约束空间变换到单纯形。

这不是双射的，不能用于 HMC。然而，它主要是逐坐标操作的（除了最终的归一化），因此适用于逐坐标优化算法。

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

变换函数，它以与 torch.stack() 兼容的方式，对 dim 处的每个子矩阵分量应用变换序列 tseq。

示例

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)

通过折断过程将非约束空间变换到多一个维度的单纯形。

此变换是 Dirichlet 分布的折断构造中迭代的 Sigmoid 变换：第一个 logit 通过 sigmoid 变换为第一个概率和其余所有概率，然后过程递归。

这是双射的，适合用于 HMC；但是它混合了坐标，不太适合优化。

class torch.distributions.transforms.Transform(cache_size=0)

可逆变换的抽象基类，具有可计算的雅可比行列式对数。它们主要用于 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 设置为派生类还应实现 log_abs_det_jacobian()。

参数:

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

变量:

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

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

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

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

property inv: Transform

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

property sign: int

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

log_abs_det_jacobian(x, y)

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

forward_shape(shape)

给定输入形状，推断前向计算的形状。默认为保持形状。

inverse_shape(shape)

给定输出形状，推断逆计算的形状。默认为保持形状。

Constraints

class torch.distributions.constraints.Constraint

约束的抽象基类。

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

变量:

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

• event_dim (int) – 定义一个事件的右侧维度数量。 check() 方法在计算有效性时将移除这么多维度。

check(value)

返回一个字节张量，其形状为 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.is_dependent(constraint)

检查 constraint 是否是 _Dependent 对象。

参数:

constraint – 一个 Constraint 对象。

返回:

如果 constraint 可以被精炼为 _Dependent 类型，则返回 True，否则返回 False。

返回类型:

布尔值

示例

>>> import torch
>>> from torch.distributions import Bernoulli
>>> from torch.distributions.constraints import is_dependent

>>> dist = Bernoulli(probs=torch.tensor([0.6], requires_grad=True))
>>> constraint1 = dist.arg_constraints["probs"]
>>> constraint2 = dist.arg_constraints["logits"]

>>> for constraint in [constraint1, constraint2]:
>>>     if is_dependent(constraint):
>>>         continue

torch.distributions.constraints.less_than

_LessThan 的别名

class torch.distributions.constraints.MixtureSameFamilyConstraint(base_constraint)

用于 MixtureSameFamily 分布的约束，该约束在执行组件分布约束的有效性检查之前，将最右边的批次维度加回。

参数:

base_constraint – MixtureSameFamily 分布的组件分布的 Constraint 对象。

check(value)

检查 value 作为 MixtureSameFamily 分布采样可能结果的有效性。

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) 查找一个不一定是双射的 Transform，从 constraints.real 到给定的 constraint。返回的变换不保证实现 .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() 注册表对于 Hamiltonian Monte Carlo 非常有用，在 Hamiltonian Monte Carlo 中，来自具有受约束 .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_to 和 biject_to 不同的一个例子是 constraints.simplex： transform_to(constraints.simplex) 返回一个 SoftmaxTransform，它只是对其输入进行指数化和归一化；这是一个便宜且大部分逐坐标的操作，适用于 SVI 等算法。相反， biject_to(constraints.simplex) 返回一个 StickBreakingTransform，它将其输入映射到一个维度少一的空间；这是一个更昂贵、数值稳定性较差的变换，但对于 HMC 等算法是必需的。

biject_to 和 transform_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

用于链接约束和变换的注册表。

register(constraint, factory=None)

将 Constraint 子类注册到此注册表中。用法

@my_registry.register(MyConstraintClass)
def construct_transform(constraint):
    assert isinstance(constraint, MyConstraint)
    return MyTransform(constraint.arg_constraints)

参数:

• constraint (子类 Constraint) – Constraint 的子类，或所需类的单例对象。

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