機率分佈 - torch.distributions

distributions 封包包含可參數化的機率分佈和取樣函數。 這允許建構隨機計算圖和隨機梯度估計器以進行最佳化。 此封包通常遵循 TensorFlow Distributions 封包的設計。

無法直接對隨機樣本進行反向傳播。然而，有兩種主要方法可以建立可進行反向傳播的替代函數。它們分別是分數函數估計器/概似比估計器/REINFORCE 和路徑導數估計器。REINFORCE 通常被視為強化學習中策略梯度方法的基礎，而路徑導數估計器常見於變分自動編碼器中的重參數化技巧。雖然分數函數只需要樣本的值 $f(x)$，但路徑導數需要導數 $f'(x)$。接下來的章節將在強化學習範例中討論這兩種方法。更多詳細資訊請參閱Gradient Estimation Using Stochastic Computation Graphs。

分數函數

當機率密度函數對其參數可微分時，我們只需要 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()

路徑導數

實作這些隨機/策略梯度（stochastic/policy gradients）的另一種方式是使用來自 rsample() 方法的重新參數化技巧（reparameterization trick），其中參數化的隨機變數可以透過無參數隨機變數的參數化確定性函數來建構。因此，重新參數化的樣本變得可微分。實作路徑導數（pathwise derivative）的程式碼如下：

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=torch.Size([]), event_shape=torch.Size([]), validate_args=None)

基類：object

Distribution 是機率分佈的抽象基底類別。

property arg_constraints: Dict[str, Constraint]

傳回一個字典，將參數名稱對應到 Constraint 物件，這些物件應由這個分佈的每個參數滿足。非張量的 Args 不需要出現在這個字典中。

property batch_shape: Size

傳回參數批次處理（batched）的形狀。

cdf(value)

傳回在 value 評估的累積密度/質量函數（cumulative density/mass function）。

參數

value (Tensor) –

傳回類型

Tensor

entropy()

傳回分佈的熵（entropy），在 batch_shape 上進行批次處理。

傳回

形狀為 batch_shape 的 Tensor。

傳回類型

Tensor

enumerate_support(expand=True)

傳回包含離散分佈支援的所有值的張量（tensor）。結果將在維度 0 上枚舉，因此結果的形狀將為 (cardinality,) + batch_shape + event_shape（對於單變數分佈，event_shape = ()）。

請注意，這會以鎖定步調（lock-step）枚舉所有批次張量 [[0, 0], [1, 1], …]。使用 expand=False，枚舉發生在維度 0 上，但剩餘的批次維度是單例維度 [[0], [1], ..。

要迭代完整笛卡爾積（Cartesian product），請使用 itertools.product(m.enumerate_support())。

參數

expand (bool) – 是否擴展批次維度上的支援，以符合分佈的 batch_shape。

傳回

在維度 0 上迭代的 Tensor。

傳回類型

Tensor

property event_shape: Size

傳回單個樣本的形狀（不進行批次處理）。

expand(batch_shape, _instance=None)

傳回新的分佈實例（或填入由衍生類別提供的現有實例），其批次維度擴展到 batch_shape。此方法在分佈的參數上呼叫 expand。因此，這不會為擴展的分佈實例分配新的記憶體。此外，這不會重複在 __init__.py 中的任何參數檢查或參數廣播（broadcasting），當首次建立實例時。

參數

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

• _instance – 由需要覆寫 .expand 的子類別提供的新實例。

傳回

新的分布實例，其批次維度已擴展到 batch_size。

icdf(value)

傳回在 value 處評估的反向累積密度/質量函數。

參數

value (Tensor) –

傳回類型

Tensor

log_prob(value)

傳回在 value 處評估的機率密度/質量函數的對數值。

參數

value (Tensor) –

傳回類型

Tensor

property mean: Tensor

傳回分布的平均值。

property mode: Tensor

傳回分布的眾數。

perplexity()

傳回分布的困惑度，並在 batch_shape 上進行批次處理。

傳回

形狀為 batch_shape 的 Tensor。

傳回類型

Tensor

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

產生一個 sample_shape 形狀的可重新參數化樣本，如果分布參數是批次的，則產生 sample_shape 形狀的一批可重新參數化樣本。

傳回類型

Tensor

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

產生一個 sample_shape 形狀的樣本，如果分布參數是批次的，則產生 sample_shape 形狀的一批樣本。

傳回類型

Tensor

sample_n(n)

產生 n 個樣本，如果分布參數是批次的，則產生 n 批樣本。

傳回類型

Tensor

static set_default_validate_args(value)

設定是否啟用或停用驗證。

預設行為模仿 Python 的 assert 語句：預設情況下驗證是開啟的，但如果在最佳化模式下執行 Python（透過 python -O）則會停用驗證。驗證可能很耗費資源，因此您可能希望在模型正常運作後停用它。

參數

value (bool) – 是否啟用驗證。

property stddev: Tensor

傳回分布的標準差。

property support: Optional[Any]

傳回一個表示此分布支持度的 Constraint 物件。

property variance: Tensor

傳回分布的變異數。

指數族

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

繼承自：Distribution

ExponentialFamily 是一個機率分佈的抽象基底類別，這些機率分佈屬於指數族，其機率質量/密度函數的形式如下定義：

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

其中 $\theta$ 表示自然參數， $t(x)$ 表示充分統計量， $F(\theta)$ 是給定族的對數正規化函數，而 $k(x)$ 是載體測度。

注意

這個類別是 Distribution 類別和屬於指數族的分布之間的中介，主要目的是檢查 .entropy() 和解析 KL 散度方法的正確性。 我們使用這個類別來使用 AD 框架和 Bregman 散度（由 Frank Nielsen 和 Richard Nock 提供，Entropies and Cross-entropies of Exponential Families）計算熵和 KL 散度。

entropy()

使用對數正規化器的 Bregman 散度來計算熵的方法。

Bernoulli

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

繼承自：ExponentialFamily

創建一個 Bernoulli 分佈，其參數由 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 的對數勝算

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

property mean

property mode

property param_shape

property probs

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

support = Boolean()

property 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 或 Tensor) – 分佈的第一個集中參數（通常稱為 alpha）

• concentration0 (float 或 Tensor) – 分佈的第二個集中參數（通常稱為 beta）

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

property concentration0

property concentration1

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean

property mode

rsample(sample_shape=())

傳回類型

Tensor

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)

繼承自：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 或 Tensor) – Bernoulli 試驗的次數

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

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

has_enumerate_support = True

log_prob(value)

property logits

property mean

property mode

property param_shape

property probs

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

property support

property variance

Categorical

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

繼承自：Distribution

建立一個 categorical 分佈，其參數可以是 probs 或 logits (但不能同時使用兩者)。

注意

它等同於 torch.multinomial() 取樣的分佈。

樣本是來自 $\{0, \ldots, K-1\}$ 的整數，其中 K 是 probs.size(-1)。

如果 probs 是一維的，長度為 K，則每個元素都是在該索引處取樣類別的相對機率。

如果 probs 是 N 維的，則前 N-1 維被視為相對機率向量的批次。

注意

probs 參數必須是非負數、有限且具有非零總和，並且將被正規化為沿著最後一個維度總和為 1。 probs 將傳回此正規化的值。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 (Tensor) – 事件機率

• logits (Tensor) – 事件對數機率（未正規化）

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

property mean

property mode

屬性 param_shape

屬性 probs

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

屬性 support

屬性 variance

柯西分布 (Cauchy)

類別 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 或 Tensor) – 分佈的眾數或中位數。

• scale (float 或 Tensor) – 半高寬 (half width at half maximum)。

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=torch.Size([]))

傳回類型

Tensor

support = Real()

屬性 variance

卡方分布 (Chi2)

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

基底類別：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

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

建立一個連續 Bernoulli 分佈，其參數由 probs 或 logits 指定（但不能同時指定）。

該分佈支持 [0, 1] 範圍，並由 'probs' (在 (0,1) 範圍內) 或 'logits' (實數值) 參數化。 請注意，與 Bernoulli 不同，'probs' 不對應於機率，而 'logits' 不對應於對數勝算，但由於與 Bernoulli 的相似性，因此使用相同的名稱。 詳情請參閱 [1]。

範例

>>> m = ContinuousBernoulli(torch.tensor([0.3]))
>>> m.sample()
tensor([ 0.2538])

參數

• probs (Number, Tensor) – (0,1) 範圍的值參數

• logits (Number, Tensor) – 實數值參數，其 sigmoid 與 'probs' 匹配

[1] The continuous Bernoulli: fixing a pervasive error in variational autoencoders, Loaiza-Ganem G and 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)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

屬性 logits

屬性 mean

屬性 param_shape

屬性 probs

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

傳回類型

Tensor

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

屬性 stddev

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

屬性 variance

Dirichlet

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

繼承自：ExponentialFamily

建立一個由濃度 concentration 參數化的 Dirichlet 分佈。

範例

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

屬性 mean

屬性 mode

rsample(sample_shape=())

傳回類型

Tensor

support = Simplex()

屬性 variance

Exponential

類別 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 (尺度)

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

property mode

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

傳回類型

Tensor

property stddev

support = GreaterThanEq(lower_bound=0.0)

property variance

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

property mode

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

傳回類型

Tensor

support = GreaterThan(lower_bound=0.0)

property variance

Gamma

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

繼承自：ExponentialFamily

建立一個 Gamma 分佈，其參數為形狀 concentration 和 rate。

範例

>>> 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) – 分佈的率參數 (通常稱為 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

property mode

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

傳回類型

Tensor

support = GreaterThanEq(lower_bound=0.0)

property variance

Geometric

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

繼承自：Distribution

建立一個幾何分佈，其參數由 probs 指定，其中 probs 是伯努利試驗成功的機率。

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

注意

torch.distributions.geometric.Geometric() $(k+1)$-th 次試驗是第一次成功，因此在 $\{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

property mean

property mode

property probs

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

support = IntegerGreaterThan(lower_bound=0)

property variance

Gumbel

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

基於: TransformedDistribution

從耿貝爾分佈 (Gumbel Distribution) 中取樣。

範例

>>> 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) – 分佈的位置參數 (Location parameter)

• scale (float 或 Tensor) – 分佈的尺度參數 (Scale parameter)

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

entropy()

expand(batch_shape, _instance=None)

log_prob(value)

property mean

property mode

property stddev

support = Real()

property variance

HalfCauchy

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

基於: TransformedDistribution

創建一個以 scale 參數化的半柯西分佈 (half-Cauchy distribution)，其中

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) – 完整柯西分佈 (full Cauchy distribution) 的尺度 (scale)

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(prob)

log_prob(value)

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)

基於: TransformedDistribution

Creates a half-normal distribution parameterized by scale where

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 (浮點數 或 張量) – 完整常態分佈的尺度 (scale)

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(prob)

log_prob(value)

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)

繼承自：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])]

參數

• base_distribution (torch.distributions.distribution.Distribution) – 基礎分佈

• reinterpreted_batch_ndims (int) – 要重新解釋為事件維度的批次維度數量

arg_constraints: Dict[str, Constraint] = {}

entropy()

enumerate_support(expand=True)

expand(batch_shape, _instance=None)

property has_enumerate_support

property has_rsample

log_prob(value)

property mean

property mode

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

傳回類型

Tensor

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

property support

property variance

反伽瑪 (InverseGamma)

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

基於: 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 (通常稱為 beta)

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

property concentration

entropy()

expand(batch_shape, _instance=None)

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)

基於: 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 或 Tensor) – 分佈的第一個集中參數（通常稱為 alpha）

• concentration0 (float 或 Tensor) – 分佈的第二個集中參數（通常稱為 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

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)

繼承自：Distribution

用於相關矩陣的下三角 Cholesky 分解的 LKJ 分佈。該分佈由 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) – 分佈的集中度/形狀參數（通常稱為 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=torch.Size([]))

support = CorrCholesky()

Laplace

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

繼承自：Distribution

建立一個以 loc 和 scale 為參數的 Laplace 分佈。

範例

>>> 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) – 分佈的尺度

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

property mode

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

傳回類型

Tensor

property stddev

support = Real()

property variance

LogNormal

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

基於: 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) – 分佈對數的平均值

• scale (float 或 Tensor) – 分佈對數的標準差

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

entropy()

expand(batch_shape, _instance=None)

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)

繼承自：Distribution

建立一個多元常態分佈，其共變異數矩陣具有低秩形式，並由 cov_factor 和 cov_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()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean

property mode

property precision_matrix

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

傳回類型

Tensor

property scale_tril

support = IndependentConstraint(Real(), 1)

property variance

MixtureSameFamily

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

繼承自：Distribution

MixtureSameFamily 分佈實作了 (一批) 混合分佈，其中所有成分都來自相同分佈類型的不同參數化。它由一個 Categorical “選擇分佈”（在 k 個成分上）和一個成分分佈參數化，即一個 Distribution，其最右邊的批次形狀（等於 [k]）索引每個（批次）成分。

範例

>>> # 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 – 類似 torch.distributions.Categorical 的實例。管理選擇成分的機率。類別數量必須與 component_distribution 的最右邊批次維度相符。必須具有純量 batch_shape 或與 component_distribution.batch_shape[:-1] 相符的 batch_shape。

• component_distribution – 類似 torch.distributions.Distribution 的實例。最右邊的批次維度索引成分。

arg_constraints: Dict[str, Constraint] = {}

cdf(x)

property component_distribution

expand(batch_shape, _instance=None)

has_rsample = False

log_prob(x)

property mean

property mixture_distribution

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

property support

property variance

Multinomial

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

繼承自：Distribution

建立一個以 total_count 和 probs 或 logits (但不能同時指定兩者) 為參數的多項式分佈。 probs 的最內層維度會對類別進行索引。所有其他維度會對批次進行索引。

請注意，如果只呼叫 log_prob()，則不需要指定 total_count（請參閱以下範例）

注意

probs 引數必須為非負數、有限且總和不為零，並且將會被正規化，使其沿著最後一個維度加總為 1。 probs 將會傳回這個正規化的值。 logits 引數將會被解譯為未正規化的對數機率，因此可以是任何實數。同樣地，它也會被正規化，使得到的機率沿著最後一個維度加總為 1。 logits 將會傳回這個正規化的值。

• sample() 需要一個所有參數和樣本共用的 total_count。

• log_prob() 允許每個參數和樣本有不同的 total_count。

範例

>>> 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) – 試驗次數

• probs (Tensor) – 事件機率

• logits (Tensor) – 事件對數機率（未正規化）

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

entropy()

expand(batch_shape, _instance=None)

log_prob(value)

property logits

property mean

property param_shape

property probs

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

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)

繼承自：Distribution

建立一個以平均向量和共變異數矩陣為參數的多元常態（也稱為高斯）分佈。

多元常態分佈可以使用正定共變異數矩陣 $\mathbf{\Sigma}$ 或正定精確度矩陣 $\mathbf{\Sigma}^{-1}$ 或對角線值為正值的下三角矩陣 $\mathbf{L}$ 來參數化，使得 $\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_matrix 或 precision_matrix 或 scale_tril 其中之一。

使用 scale_tril 會更有效率：所有內部計算都基於 scale_tril。如果改為傳遞 covariance_matrix 或 precision_matrix，則只會用來使用 Cholesky 分解計算對應的下三角矩陣。

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

property covariance_matrix

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean

property mode

property precision_matrix

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

傳回類型

Tensor

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)

繼承自：Distribution

創建一個負二項分佈，即在達到 total_count 次失敗之前，成功獨立且相同的 Bernoulli 試驗次數的分佈。每次 Bernoulli 試驗的成功機率為 probs。

參數

• total_count ( float 或 Tensor) – 非負的負二項試驗次數，用於停止試驗。即使是實數值計數，此分佈仍然有效。

• probs ( Tensor) – 事件在半開區間 [0, 1) 內成功的機率。

• logits ( Tensor) – 事件成功的機率的對數 odds。

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

property mean

property mode

property param_shape

property probs

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

support = IntegerGreaterThan(lower_bound=0)

property variance

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

property mode

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

傳回類型

Tensor

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

property stddev

support = Real()

property variance

OneHotCategorical

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

繼承自：Distribution

建立一個 one-hot categorical 分布，其參數由 probs 或 logits 指定。

樣本是大小為 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 (Tensor) – 事件機率

• logits (Tensor) – 事件對數機率（未正規化）

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

屬性 probs

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

support = OneHot()

屬性 variance

Pareto

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

基於: TransformedDistribution

從 Pareto Type 1 分布中取樣。

範例

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

• alpha (float or Tensor) – 分布的形狀參數

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

entropy()

expand(batch_shape, _instance=None)

屬性 mean

屬性 mode

屬性 support

屬性 variance

Poisson

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

繼承自：ExponentialFamily

建立一個以 rate 作為參數的 Poisson 分布，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

property mode

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

support = IntegerGreaterThan(lower_bound=0)

property variance

RelaxedBernoulli

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

基於: 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)}

expand(batch_shape, _instance=None)

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)

繼承自：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

property param_shape

property probs

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

傳回類型

Tensor

support = Real()

RelaxedOneHotCategorical

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

基於: 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 (Tensor) – 事件機率

• logits (Tensor) – 每個事件的未正規化對數機率

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

expand(batch_shape, _instance=None)

has_rsample = True

property logits

property probs

support = Simplex()

property temperature

StudentT

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

繼承自：Distribution

建立一個 Student’s t 分佈，其參數為自由度 df、平均值 loc 和尺度 scale。

範例

>>> 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) – 分佈的尺度

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

property mode

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

傳回類型

Tensor

support = Real()

property variance

TransformedDistribution

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

繼承自：Distribution

Distribution 類別的擴展，將一系列 Transforms 應用於基礎分布。 令 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

icdf(value)

使用轉換並計算基礎分佈的分數來計算反向累積分佈函數。

log_prob(value)

通過反轉轉換並使用基礎分佈的分數和 log abs det jacobian 計算分數來對樣本進行評分。

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

如果分佈參數已批次處理，則生成 sample_shape 形狀的重新參數化樣本或 sample_shape 形狀的重新參數化樣本批次。 首先從基礎分佈中採樣，並為列表中的每個轉換應用 transform()。

傳回類型

Tensor

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

產生一個 `sample_shape` 形狀的樣本，或者，如果分配參數已批次處理，則產生一個 `sample_shape` 形狀的樣本批次。首先從基礎分配中取樣，然後對列表中的每個轉換應用 transform()。

property support

均勻分佈 (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) – 上限（不包含）。

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

cdf(value)

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

icdf(value)

log_prob(value)

property mean

property mode

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

傳回類型

Tensor

property stddev

property support

property variance

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

所提供的平均值是循環平均值。

property mode

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

von Mises 分佈的抽樣演算法基於以下論文：D.J. Best 和 N.I. Fisher，“Efficient simulation of the von Mises distribution.” Applied Statistics (1979): 152-157。

為了避免在濃度較小的情況下，於 _rejection_sample() 發生停滯（對於單精度，從 1e-4 附近開始發生，請參閱問題 #88443），抽樣始終在內部以雙精度完成。

support = Real()

property variance

所提供的變異數是循環變異數。

Weibull

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

基於: 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)。

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

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)

繼承自：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) – 正定共變異數矩陣

• precision_matrix (Tensor) – 正定精確度矩陣

• scale_tril (Tensor) – 共變異數的下三角因子，具有正值的對角線

注意

只能指定 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.

arg_constraints = {'covariance_matrix': PositiveDefinite(), 'df': GreaterThan(lower_bound=0), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}

property covariance_matrix

entropy()

expand(batch_shape, _instance=None)

has_rsample = True

log_prob(value)

property mean

property mode

property precision_matrix

rsample(sample_shape=torch.Size([]), max_try_correction=None)

警告

在某些情況下，基於 Bartlett 分解的抽樣演算法可能會傳回奇異矩陣樣本。 預設會執行幾次校正奇異樣本的嘗試，但最終可能會傳回奇異矩陣樣本。 奇異樣本可能會在 .log_prob() 中傳回 -inf 值。 在這些情況下，使用者應驗證樣本，並相應地修正 df 的值或調整 .rsample 中參數的 max_try_correction 值。

傳回類型

Tensor

property scale_tril

support = PositiveDefinite()

property variance

KL 散度

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 散度。

傳回類型

Tensor

引發

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

• Normal 和 Exponential

• Normal 和 Gamma

• Normal 和 Gumbel

• Normal 和 Laplace

• Normal 和 Normal

• Normal 和 Pareto

• Normal 和 Uniform

• OneHotCategorical 和 OneHotCategorical

• Pareto 和 Beta

• Pareto 和 ContinuousBernoulli

• Pareto 和 Exponential

• Pareto 和 Gamma

• Pareto 和 Normal

• Pareto 和 Pareto

• Pareto 和 Uniform

• Poisson 和 Bernoulli

• Poisson 和 Binomial

• Poisson 和 Poisson

• TransformedDistribution 和 TransformedDistribution

• Uniform 和 Beta

• Uniform 和 ContinuousBernoulli

• Uniform 與 Exponential

• Uniform 與 Gamma

• Uniform 與 Gumbel

• Uniform 與 Normal

• Uniform 與 Pareto

• Uniform 與 Uniform

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 的子類別。

Transforms

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)

轉換 functor，以與 torch.cat() 相容的方式，將一系列轉換 tseq 以分量方式應用於 dim 處的每個子矩陣，其長度為 lengths[dim]。

範例

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 ( Transform 的列表) – 要組合的轉換列表。

• cache_size ( int ) – 快取大小。如果為零，則不進行快取。如果為一，則快取最新的單個值。僅支援 0 和 1。

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

將長度為 $D*(D-1)/2$ 的不受約束的實向量 $x$ 轉換為 D 維相關矩陣的 Cholesky 因子。 此 Cholesky 因子是一個下三角矩陣，其對角線為正，且每行的歐幾里得範數為單位。 轉換過程如下：

1. 首先，我們按行順序將 x 轉換為下三角矩陣。

2. For each row $X_i$ of the lower triangular part, we apply a signed version of class StickBreakingTransform to transform $X_i$ into a unit Euclidean length vector using the following steps: - Scales into the interval $(-1, 1)$ domain: $r_i = \tanh(X_i)$. - Transforms into an unsigned domain: $z_i = r_i^2$. - Applies $s_i = StickBreakingTransform(z_i)$. - Transforms back into signed domain: $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)

單位 Jacobian 轉換，用於重新調整張量最右邊部分的形狀。

請注意，in_shape 和 out_shape 必須具有相同數量的元素，就像 torch.Tensor.reshape() 一樣。

參數

• in_shape (torch.Size) – 輸入事件形狀。

• out_shape (torch.Size) – 輸出事件形狀。

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., 2.), SigmoidTransform(), AffineTransform(-1., 2.)]) `。然而，這可能在數值上不穩定，因此建議改用 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)

轉換函子，將轉換序列 tseq 以 component-wise 的方式應用於 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)

通過折棍 (stick-breaking) 過程將無約束空間轉換為具有一個額外維度的單純形。

此轉換作為 Dirichlet 分佈的折棍構造中的迭代 sigmoid 轉換出現：第一個 logit 通過 sigmoid 轉換為第一個機率和其餘所有事物的機率，然後該過程遞迴。

這是雙射的，適合在 HMC 中使用；但是它將座標混合在一起，不太適合優化。

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

具有可計算的 log det jacobians 的可逆變換的抽象類別。它們主要用於 torch.distributions.TransformedDistribution。

快取對於反函數計算成本高昂或數值不穩定的轉換非常有用。請注意，由於 autograd 圖可能會被反轉，因此必須小心使用記憶化的值。例如，以下程式碼無論有無快取都可以正常運作：

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 是雙射的，若且唯若對於 domain 中的每個 x 和 codomain 中的每個 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。 這應滿足 t.inv.inv is t。

property sign

如果適用，則傳回雅可比行列式符號。 一般來說，這僅對雙射轉換有意義。

log_abs_det_jacobian(x, y)

計算給定輸入和輸出的 log det jacobian log |dy/dx|。

forward_shape(shape)

給定輸入形狀，推斷正向計算的形狀。 預設為保留形狀。

inverse_shape(shape)

給定輸出形狀，推斷反向計算的形狀。 預設為保留形狀。

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

約束條件的抽象基底類別。

約束條件物件代表變數有效的區域，例如變數可以被最佳化的範圍。

變數

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

傳回類型

bool

範例

>>> 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 的別名

torch.distributions.constraints.multinomial

_Multinomial 的別名

torch.distributions.constraints.stack

_Stack 的別名

約束條件註冊表

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），但不一定是對射 (bijective) 轉換。 不保證返回的轉換會實作 .log_abs_det_jacobian()。

transform_to() 登錄檔 (registry) 可用於對機率分布的受約束參數執行無約束的最佳化，這些參數由每個分布的 .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，其中具有受約束 .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 物件。