[doc] two diff meanings of rv generated by torch.tensor.geometric_ an…

…d torch.distributions.geometric.Geometric (pytorch#113183)

The meaning of random variables generated by `torch.tensor.geometric_` and `torch.distributions.geometric.Geometric` are different, and they are defined by two different PMFs.
Inform the user, so the user can choose their desired one.

Background: pytorch#37984 (comment)

Pull Request resolved: pytorch#113183
Approved by: https://github.com/albanD

torch/_tensor_docs.py

@@ -2114,8 +2114,12 @@ def add_docstr_all(method, docstr):
 
 .. math::
 
-    P(X=k) = (1 - p)^{k - 1} p
+    P(X=k) = (1 - p)^{k - 1} p, k = 1, 2, ...
 
+.. note::
+  :func:`torch.Tensor.geometric_` `k`-th trial is the first success hence draws samples in :math:`\{1, 2, \ldots\}`, whereas
+  :func:`torch.distributions.geometric.Geometric` :math:`(k+1)`-th trial is the first success
+  hence draws samples in :math:`\{0, 1, \ldots\}`.
 """,
 )
 

torch/distributions/geometric.py

@@ -18,10 +18,15 @@ class Geometric(Distribution):
     r"""
     Creates a Geometric distribution parameterized by :attr:`probs`,
     where :attr:`probs` is the probability of success of Bernoulli trials.
-    It represents the probability that in :math:`k + 1` Bernoulli trials, the
-    first :math:`k` trials failed, before seeing a success.
 
-    Samples are non-negative integers [0, :math:`\inf`).
+    .. math::
+
+        P(X=k) = (1-p)^{k} p, k = 0, 1, ...
+
+    .. note::
+        :func:`torch.distributions.geometric.Geometric` :math:`(k+1)`-th trial is the first success
+        hence draws samples in :math:`\{0, 1, \ldots\}`, whereas
+        :func:`torch.Tensor.geometric_` `k`-th trial is the first success hence draws samples in :math:`\{1, 2, \ldots\}`.
 
     Example::