0
# Probability Distributions
1

2
Comprehensive collection of probability distributions for probabilistic modeling, including continuous, discrete, multivariate, and specialized distributions with automatic differentiation support.
3

4
## Capabilities
5

6
### Continuous Distributions
7

8
Fundamental continuous probability distributions for modeling real-valued random variables.
9

10
```python { .api }
11
class Normal(dist.Distribution):
12
    """
13
    Normal (Gaussian) distribution with location and scale parameters.
14
    
15
    Parameters:
16
    - loc (Tensor): Mean of the distribution
17
    - scale (Tensor): Standard deviation (must be positive)
18
    
19
    Examples:
20
    >>> normal = dist.Normal(0.0, 1.0)  # Standard normal
21
    >>> normal = dist.Normal(torch.zeros(5), torch.ones(5))  # Multivariate
22
    """
23
    def __init__(self, loc: torch.Tensor, scale: torch.Tensor): ...
24

25
class Beta(dist.Distribution):
26
    """
27
    Beta distribution parameterized by concentration parameters.
28
    
29
    Parameters:
30
    - concentration1 (Tensor): First concentration parameter (alpha > 0)
31
    - concentration0 (Tensor): Second concentration parameter (beta > 0)
32
    
33
    Examples:
34
    >>> beta = dist.Beta(1.0, 1.0)  # Uniform on [0, 1]
35
    >>> beta = dist.Beta(2.0, 5.0)  # Skewed toward 0
36
    """
37
    def __init__(self, concentration1: torch.Tensor, concentration0: torch.Tensor): ...
38

39
class Gamma(dist.Distribution):
40
    """
41
    Gamma distribution parameterized by concentration and rate.
42
    
43
    Parameters:
44
    - concentration (Tensor): Shape parameter (alpha > 0)
45
    - rate (Tensor): Rate parameter (beta > 0)
46
    
47
    Examples:
48
    >>> gamma = dist.Gamma(2.0, 1.0)  # Concentration=2, Rate=1
49
    >>> gamma = dist.Gamma(torch.ones(5), torch.ones(5))
50
    """
51
    def __init__(self, concentration: torch.Tensor, rate: torch.Tensor): ...
52

53
class Exponential(dist.Distribution):
54
    """
55
    Exponential distribution with rate parameter.
56
    
57
    Parameters:
58
    - rate (Tensor): Rate parameter (lambda > 0)
59
    """
60
    def __init__(self, rate: torch.Tensor): ...
61

62
class Uniform(dist.Distribution):
63
    """
64
    Uniform distribution over interval [low, high).
65
    
66
    Parameters:
67
    - low (Tensor): Lower bound (inclusive)
68
    - high (Tensor): Upper bound (exclusive)
69
    """
70
    def __init__(self, low: torch.Tensor, high: torch.Tensor): ...
71

72
class Laplace(dist.Distribution):
73
    """
74
    Laplace distribution with location and scale parameters.
75
    
76
    Parameters:
77
    - loc (Tensor): Location parameter (median)
78
    - scale (Tensor): Scale parameter (> 0)
79
    """
80
    def __init__(self, loc: torch.Tensor, scale: torch.Tensor): ...
81

82
class Cauchy(dist.Distribution):
83
    """
84
    Cauchy distribution with location and scale parameters.
85
    
86
    Parameters:
87
    - loc (Tensor): Location parameter
88
    - scale (Tensor): Scale parameter (> 0)
89
    """
90
    def __init__(self, loc: torch.Tensor, scale: torch.Tensor): ...
91

92
class StudentT(dist.Distribution):
93
    """
94
    Student's t-distribution with degrees of freedom.
95
    
96
    Parameters:
97
    - df (Tensor): Degrees of freedom (> 0)
98
    - loc (Tensor): Location parameter (default 0)
99
    - scale (Tensor): Scale parameter (default 1, > 0)
100
    """
101
    def __init__(self, df: torch.Tensor, loc: torch.Tensor = 0.0, scale: torch.Tensor = 1.0): ...
102
```
103

104
### Discrete Distributions
105

106
Discrete probability distributions for modeling categorical and count data.
107

108
```python { .api }
109
class Bernoulli(dist.Distribution):
110
    """
111
    Bernoulli distribution for binary outcomes.
112
    
113
    Parameters:
114
    - probs (Tensor, optional): Probability of success (0 <= p <= 1)
115
    - logits (Tensor, optional): Log-odds of success (alternative to probs)
116
    
117
    Examples:
118
    >>> bernoulli = dist.Bernoulli(0.3)  # 30% probability of 1
119
    >>> bernoulli = dist.Bernoulli(logits=torch.tensor([-1.0, 0.0, 1.0]))
120
    """
121
    def __init__(self, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
122

123
class Categorical(dist.Distribution):
124
    """
125
    Categorical distribution over discrete categories.
126
    
127
    Parameters:
128
    - probs (Tensor, optional): Category probabilities (must sum to 1)
129
    - logits (Tensor, optional): Log probabilities (alternative to probs)
130
    
131
    Examples:
132
    >>> cat = dist.Categorical(torch.tensor([0.25, 0.25, 0.5]))
133
    >>> cat = dist.Categorical(logits=torch.tensor([1.0, 1.0, 2.0]))
134
    """
135
    def __init__(self, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
136

137
class Binomial(dist.Distribution):
138
    """
139
    Binomial distribution for count data with fixed number of trials.
140
    
141
    Parameters:
142
    - total_count (Tensor): Number of trials
143
    - probs (Tensor, optional): Success probability per trial
144
    - logits (Tensor, optional): Log-odds of success (alternative to probs)
145
    """
146
    def __init__(self, total_count: torch.Tensor, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
147

148
class Poisson(dist.Distribution):
149
    """
150
    Poisson distribution for count data.
151
    
152
    Parameters:
153
    - rate (Tensor): Rate parameter (lambda > 0)
154
    """
155
    def __init__(self, rate: torch.Tensor): ...
156

157
class NegativeBinomial(dist.Distribution):
158
    """
159
    Negative binomial distribution for overdispersed count data.
160
    
161
    Parameters:
162
    - total_count (Tensor): Number of failures until stopping
163
    - probs (Tensor, optional): Success probability
164
    - logits (Tensor, optional): Log-odds of success
165
    """
166
    def __init__(self, total_count: torch.Tensor, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
167

168
class Geometric(dist.Distribution):
169
    """
170
    Geometric distribution for number of trials until first success.
171
    
172
    Parameters:
173
    - probs (Tensor, optional): Success probability
174
    - logits (Tensor, optional): Log-odds of success
175
    """
176
    def __init__(self, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
177
```
178

179
### Multivariate Distributions
180

181
Distributions for modeling correlated multi-dimensional random variables.
182

183
```python { .api }
184
class MultivariateNormal(dist.Distribution):
185
    """
186
    Multivariate normal distribution with mean vector and covariance matrix.
187
    
188
    Parameters:
189
    - loc (Tensor): Mean vector of shape (..., n)
190
    - covariance_matrix (Tensor, optional): Covariance matrix (..., n, n)
191
    - precision_matrix (Tensor, optional): Precision matrix (inverse covariance)
192
    - scale_tril (Tensor, optional): Lower triangular Cholesky factor
193
    
194
    Examples:
195
    >>> mvn = dist.MultivariateNormal(torch.zeros(3), torch.eye(3))
196
    >>> mvn = dist.MultivariateNormal(torch.zeros(3), scale_tril=torch.tril(torch.randn(3, 3)))
197
    """
198
    def __init__(self, loc: torch.Tensor, covariance_matrix: torch.Tensor = None, 
199
                 precision_matrix: torch.Tensor = None, scale_tril: torch.Tensor = None): ...
200

201
class Dirichlet(dist.Distribution):
202
    """
203
    Dirichlet distribution over probability simplices.
204
    
205
    Parameters:
206
    - concentration (Tensor): Concentration parameters (all > 0)
207
    
208
    Examples:
209
    >>> dirichlet = dist.Dirichlet(torch.ones(5))  # Uniform over 4-simplex
210
    >>> dirichlet = dist.Dirichlet(torch.tensor([1.0, 2.0, 3.0]))
211
    """
212
    def __init__(self, concentration: torch.Tensor): ...
213

214
class LowRankMultivariateNormal(dist.Distribution):
215
    """
216
    Low-rank multivariate normal distribution for high-dimensional data.
217
    
218
    Parameters:
219
    - loc (Tensor): Mean vector
220
    - cov_factor (Tensor): Low-rank covariance factor
221
    - cov_diag (Tensor): Diagonal covariance component
222
    """
223
    def __init__(self, loc: torch.Tensor, cov_factor: torch.Tensor, cov_diag: torch.Tensor): ...
224

225
class Multinomial(dist.Distribution):
226
    """
227
    Multinomial distribution for multi-category count data.
228
    
229
    Parameters:
230
    - total_count (Tensor): Total number of trials
231
    - probs (Tensor, optional): Category probabilities
232
    - logits (Tensor, optional): Log probabilities
233
    """
234
    def __init__(self, total_count: torch.Tensor = 1, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
235
```
236

237
### Pyro-Specific Distributions
238

239
Specialized distributions unique to Pyro for advanced probabilistic modeling.
240

241
```python { .api }
242
class Delta(dist.Distribution):
243
    """
244
    Point mass (Dirac delta) distribution for deterministic variables.
245
    
246
    Parameters:
247
    - v (Tensor): Point mass location
248
    - log_density (Tensor, optional): Log density at the point
249
    - event_dim (int): Number of event dimensions
250
    
251
    Examples:
252
    >>> delta = dist.Delta(torch.tensor(5.0))  # Point mass at 5.0
253
    >>> delta = dist.Delta(torch.zeros(3, 3), event_dim=2)  # Matrix point mass
254
    """
255
    def __init__(self, v: torch.Tensor, log_density: torch.Tensor = 0.0, event_dim: int = 0): ...
256

257
class Empirical(dist.Distribution):
258
    """
259
    Empirical distribution from samples with optional weights.
260
    
261
    Parameters:
262
    - samples (Tensor): Sample values
263
    - weights (Tensor, optional): Sample weights (default uniform)
264
    
265
    Examples:
266
    >>> samples = torch.randn(1000, 5)
267
    >>> empirical = dist.Empirical(samples)
268
    >>> 
269
    >>> # Weighted samples
270
    >>> weights = torch.rand(1000)
271
    >>> empirical = dist.Empirical(samples, weights)
272
    """
273
    def __init__(self, samples: torch.Tensor, weights: torch.Tensor = None): ...
274

275
class ImproperUniform(dist.Distribution):
276
    """
277
    Improper uniform distribution with infinite support.
278
    
279
    Parameters:
280
    - support (Constraint): Support constraint
281
    - batch_shape (torch.Size): Batch shape
282
    - event_shape (torch.Size): Event shape
283
    """
284
    def __init__(self, support, batch_shape: torch.Size = torch.Size(), event_shape: torch.Size = torch.Size()): ...
285

286
class Unit(dist.Distribution):
287
    """
288
    Unit distribution that always returns empty tensor.
289
    
290
    Useful as a null distribution or for testing purposes.
291
    """
292
    def __init__(self): ...
293
```
294

295
### Extended Distributions
296

297
Enhanced versions of standard distributions with additional functionality.
298

299
```python { .api }
300
class ExtendedBinomial(dist.Distribution):
301
    """
302
    Extended binomial distribution allowing non-integer total_count.
303
    
304
    Parameters:
305
    - total_count (Tensor): Total count (can be non-integer)
306
    - probs (Tensor, optional): Success probability
307
    - logits (Tensor, optional): Log-odds of success
308
    """
309
    def __init__(self, total_count: torch.Tensor, probs: torch.Tensor = None, logits: torch.Tensor = None): ...
310

311
class ExtendedBetaBinomial(dist.Distribution):
312
    """
313
    Extended beta-binomial distribution with continuous total count.
314
    
315
    Parameters:
316
    - concentration1 (Tensor): First beta parameter
317
    - concentration0 (Tensor): Second beta parameter  
318
    - total_count (Tensor): Total count
319
    """
320
    def __init__(self, concentration1: torch.Tensor, concentration0: torch.Tensor, total_count: torch.Tensor): ...
321

322
class SkewLogistic(dist.Distribution):
323
    """
324
    Skewed logistic distribution.
325
    
326
    Parameters:
327
    - loc (Tensor): Location parameter
328
    - scale (Tensor): Scale parameter
329
    - skewness (Tensor): Skewness parameter
330
    """
331
    def __init__(self, loc: torch.Tensor, scale: torch.Tensor, skewness: torch.Tensor): ...
332
```
333

334
### Mixture Distributions
335

336
Distributions for modeling multi-modal and heterogeneous data.
337

338
```python { .api }
339
class MixtureSameFamily(dist.Distribution):
340
    """
341
    Mixture distribution with same family components.
342
    
343
    Parameters:
344
    - mixture_distribution (Categorical): Mixing distribution
345
    - component_distribution (Distribution): Component distribution
346
    
347
    Examples:
348
    >>> mix = dist.Categorical(torch.ones(3))
349
    >>> comp = dist.Normal(torch.tensor([0.0, 5.0, -5.0]), torch.ones(3))
350
    >>> mixture = dist.MixtureSameFamily(mix, comp)
351
    """
352
    def __init__(self, mixture_distribution, component_distribution): ...
353

354
class MixtureOfDiagNormals(dist.Distribution):
355
    """
356
    Mixture of diagonal multivariate normal distributions.
357
    
358
    Parameters:
359
    - locs (Tensor): Component means
360
    - coord_scale (Tensor): Component scales
361
    - component_logits (Tensor): Component log probabilities
362
    """
363
    def __init__(self, locs: torch.Tensor, coord_scale: torch.Tensor, component_logits: torch.Tensor): ...
364

365
class GaussianScaleMixture(dist.Distribution):
366
    """
367
    Gaussian scale mixture distribution.
368
    
369
    Parameters:
370
    - loc (Tensor): Location parameter
371
    - mixture_distribution (Distribution): Scale mixing distribution
372
    - component_distribution (Distribution): Component distribution
373
    """
374
    def __init__(self, loc: torch.Tensor, mixture_distribution, component_distribution): ...
375
```
376

377
### Zero-Inflated Distributions
378

379
Distributions for modeling data with excess zeros.
380

381
```python { .api }
382
class ZeroInflatedDistribution(dist.Distribution):
383
    """
384
    Zero-inflated version of any distribution.
385
    
386
    Parameters:
387
    - base_dist (Distribution): Base distribution
388
    - gate (Tensor): Probability of zero inflation
389
    
390
    Examples:
391
    >>> base = dist.Poisson(3.0)
392
    >>> zi = dist.ZeroInflatedDistribution(base, gate=0.2)
393
    """
394
    def __init__(self, base_dist, gate: torch.Tensor): ...
395

396
class ZeroInflatedPoisson(dist.Distribution):
397
    """
398
    Zero-inflated Poisson distribution.
399
    
400
    Parameters:
401
    - rate (Tensor): Poisson rate parameter
402
    - gate (Tensor): Zero-inflation probability
403
    """
404
    def __init__(self, rate: torch.Tensor, gate: torch.Tensor): ...
405

406
class ZeroInflatedNegativeBinomial(dist.Distribution):
407
    """
408
    Zero-inflated negative binomial distribution.
409
    
410
    Parameters:
411
    - total_count (Tensor): Number of failures
412
    - probs (Tensor, optional): Success probability
413
    - logits (Tensor, optional): Log-odds of success  
414
    - gate (Tensor): Zero-inflation probability
415
    """
416
    def __init__(self, total_count: torch.Tensor, probs: torch.Tensor = None, 
417
                 logits: torch.Tensor = None, gate: torch.Tensor = None): ...
418
```
419

420
### Time Series Distributions
421

422
Distributions for modeling temporal and sequential data.
423

424
```python { .api }
425
class DiscreteHMM(dist.Distribution):
426
    """
427
    Discrete Hidden Markov Model distribution.
428
    
429
    Parameters:
430
    - initial_logits (Tensor): Initial state log probabilities
431
    - transition_logits (Tensor): Transition log probabilities
432
    - observation_dist (Distribution): Observation distribution
433
    """
434
    def __init__(self, initial_logits: torch.Tensor, transition_logits: torch.Tensor, observation_dist): ...
435

436
class GaussianHMM(dist.Distribution):
437
    """
438
    Gaussian Hidden Markov Model with continuous observations.
439
    
440
    Parameters:
441
    - initial_dist (Distribution): Initial state distribution
442
    - transition_matrix (Tensor): Transition probabilities
443
    - observation_matrix (Tensor): Observation matrix
444
    - observation_dist (Distribution): Observation noise distribution
445
    """
446
    def __init__(self, initial_dist, transition_matrix: torch.Tensor, 
447
                 observation_matrix: torch.Tensor, observation_dist): ...
448

449
class LinearHMM(dist.Distribution):
450
    """
451
    Linear Gaussian state space model.
452
    
453
    Parameters:
454
    - initial_dist (Distribution): Initial state distribution
455
    - transition_matrix (Tensor): State transition matrix
456
    - transition_dist (Distribution): Transition noise
457
    - observation_matrix (Tensor): Observation matrix
458
    - observation_dist (Distribution): Observation noise
459
    """
460
    def __init__(self, initial_dist, transition_matrix: torch.Tensor, transition_dist,
461
                 observation_matrix: torch.Tensor, observation_dist): ...
462
```
463

464
## Distribution Utilities
465

466
### Validation and Control
467

468
```python { .api }
469
def enable_validation(is_validate: bool = True):
470
    """
471
    Enable or disable validation for all distributions.
472
    
473
    Parameters:
474
    - is_validate (bool): Whether to enable validation
475
    """
476

477
def is_validation_enabled() -> bool:
478
    """
479
    Check if validation is currently enabled.
480
    
481
    Returns:
482
    bool: True if validation is enabled
483
    """
484

485
def validation_enabled() -> bool:
486
    """
487
    Context manager for temporarily enabling/disabling validation.
488
    
489
    Returns:
490
    bool: Current validation state
491
    """
492
```
493

494
## Examples
495

496
### Basic Distribution Usage
497

498
```python
499
import pyro.distributions as dist
500
import torch
501

502
# Continuous distributions
503
normal = dist.Normal(0.0, 1.0)
504
sample = normal.sample()
505
log_prob = normal.log_prob(sample)
506

507
# Discrete distributions
508
categorical = dist.Categorical(torch.tensor([0.2, 0.3, 0.5]))
509
category = categorical.sample()
510

511
# Multivariate distributions
512
mvn = dist.MultivariateNormal(torch.zeros(3), torch.eye(3))
513
vector_sample = mvn.sample()
514
```
515

516
### Parameterized Distributions
517

518
```python
519
# Learnable distribution parameters
520
mu = pyro.param("mu", torch.tensor(0.0))
521
sigma = pyro.param("sigma", torch.tensor(1.0), constraint=dist.constraints.positive)
522

523
# Use in model
524
def model():
525
    return pyro.sample("x", dist.Normal(mu, sigma))
526
```
527

528
### Custom Mixture Model
529

530
```python
531
def mixture_model():
532
    # Mixing weights
533
    weights = pyro.sample("weights", dist.Dirichlet(torch.ones(3)))
534
    
535
    # Component parameters
536
    locs = pyro.sample("locs", dist.Normal(0, 5).expand([3]).to_event(1))
537
    scales = pyro.sample("scales", dist.LogNormal(0, 1).expand([3]).to_event(1))
538
    
539
    # Mixture distribution
540
    mix = dist.Categorical(weights)
541
    comp = dist.Normal(locs, scales).to_event(1)
542
    mixture = dist.MixtureSameFamily(mix, comp)
543
    
544
    return pyro.sample("obs", mixture)
545
```