torch.distributions.Geometric

class Geometric extends Distribution

new Geometric(options: { probs?: number | Tensor; logits?: number | Tensor } & DistributionOptions)

readonlyarg_constraints(unknown)
readonlysupport(unknown)
readonlyprobs(Tensor): – Get probs, computing from logits if needed.
readonlylogits(Tensor): – Get logits, computing from probs if needed.
readonlymean(Tensor)
readonlymode(Tensor)
readonlyvariance(Tensor)

Geometric distribution: models the number of failures before the first success in Bernoulli trials.

Parameterized by success probability p. Represents the count of failures (0, 1, 2, ...) that occur before getting one success. If you flip a coin until it lands heads, the number of tails you see follows a Geometric distribution. Essential for:

Modeling waiting times and delay until first occurrence
Counting failures before first success
Reliability and failure analysis (time to first fault)
Memoryless processes (queue modeling, customer wait times)
Discrete-time survival and lifetime analysis
Ruin probability and gambler's ruin problems
Queuing theory and process reliability

Convention Note: This implementation follows PyTorch's convention: X ∈ {0, 1, 2, ...} is the number of FAILURES before first success. Some textbooks instead use X ∈ {1, 2, 3, ...} for the trial number of the first success (add 1 to convert between conventions).

Key Property - Memoryless: The geometric distribution is memoryless: P(X > n + k | X > n) = P(X > k). This means the number of additional failures you need doesn't depend on how many failures you've already had.

\begin{aligned} \text{PMF: } P(X = k) = (1-p)^k p \quad k = 0,1,2,\ldots \\ \text{Mean: } \mathbb{E}[X] = \frac{1-p}{p} = \frac{q}{p} \\ \text{Variance: } \text{Var}(X) = \frac{1-p}{p^2} = \frac{q}{p^2} \\ \text{Mode: } 0 \quad \text{(always most likely)} \\ \text{Entropy: } H(X) = -\frac{(1-p)\ln(1-p) + p\ln(p)}{p} \\ \text{Memoryless: } P(X > m+n | X > m) = P(X > n) \quad \text{(only continuous or discrete geometric)} \end{aligned}

Convention matters: X = number of failures (not trial number). Add 1 for "trial of first success"
Always starts at 0: Mode is always 0 (probability highest at k=0)
Mean = (1-p)/p: Proportional to 1/p; high p → small expected wait
Variance = (1-p)/p²: Variance grows faster than mean as p decreases
Memoryless property: Only distribution with this property (aside from exponential)
Extreme p values: p→0 gives unbounded wait; p→1 gives always 0
Discrete analog of exponential: Exponential is continuous memoryless; Geometric is discrete

p must be in (0,1]: p=0 or p1 causes errors or invalid behavior
Large expected values: With small p, samples can be very large (e.g., p=0.01 → E[X]=99)
Probs vs Logits: Use logits for numerical stability with extreme probabilities
Integer conversion: Some libraries use 1-indexed convention; this uses 0-indexed

Examples

// Fair coin flips: 50% chance of heads
// Count tails before first heads
const fair = new torch.distributions.Geometric({ probs: 0.5 });
const num_tails = fair.sample();  // typically 0-3, rarely more
const tails_before_first_heads = fair.sample([1000]);  // 1000 trials

// Biased coin: 10% chance of success (90% of failing)
// On average, we expect 9 failures before 1 success
const biased = new torch.distributions.Geometric({ probs: 0.1 });
const expected_failures = biased.mean;  // = (1-0.1)/0.1 = 9
const samples = biased.sample([100]);  // 100 samples

// Quality control: probability of defects
// If product failure rate is 0.05, how many pass before first failure?
const failure_rate = 0.05;  // 5% fail\n * const quality_dist = new torch.distributions.Geometric({ probs: failure_rate });
const passes_before_failure = quality_dist.sample();  // typical: 15-20\n * const expected_good_units = quality_dist.mean;  // (1-0.05)/0.05 = 19\n *
// Customer service: calls until successful resolution
// Resolution rate p=0.8 (80% of calls resolve the issue)
const resolution_rate = 0.8;
const service_dist = new torch.distributions.Geometric({ probs: resolution_rate });
const failed_attempts = service_dist.sample();  // failed calls before success
const expected_attempts = 1 + service_dist.mean.item();  // total attempts (including successful one)\n *
// Batched distributions with different success rates
const probs = torch.tensor([0.1, 0.3, 0.5, 0.7, 0.9]);  // different success rates
const dist = new torch.distributions.Geometric({ probs });  // [5] batch shape
const samples = dist.sample();  // [5] shaped samples
// p=0.1: mostly large values; p=0.9: mostly small values
const means = dist.mean;  // [9, 2.33, 1, 0.43, 0.11]\n *
// Memoryless property: past failures don't affect future
// P(10+ more failures | already 20 failures) = P(10+ failures)
const dist = new torch.distributions.Geometric({ probs: 0.5 });
// If already waited for 20 failures, expected additional: still 1
const expected_additional = dist.mean;  // same regardless of history

// Entropy: uncertainty in the distribution
const certain = new torch.distributions.Geometric({ probs: 0.99 });
const entropy_low = certain.entropy();  // near 0 (will likely be 0)
const fair = new torch.distributions.Geometric({ probs: 0.5 });
const entropy_high = fair.entropy();  // larger (more uncertain)