mirror of
https://github.com/pytorch/pytorch.git
synced 2025-10-20 21:14:14 +08:00
9e8f27cc79
Options to address the "undocumented python objects": 1. Reference the functions in the .rst via the torch.nn.modules namespace. Note that this changes the generated doc filenames / locations for most of these functions! 2. [Not an option] Monkeypatch `__module__` for these objects (broke several tests in CI due to `inspect.findsource` failing after this change) 3. Update the .rst files to also document the torch.nn.modules forms of these functions, duplicating docs. #### [this is the docs page added](https://docs-preview.pytorch.org/pytorch/pytorch/158491/nn.aliases.html) This PR takes option 3 by adding an rst page nn.aliases that documents the aliases in nested namespaces, removing all the torch.nn.modules.* entries from the coverage skiplist except - NLLLoss2d (deprecated) - Container (deprecated) - CrossMapLRN2d (what is this?) - NonDynamicallyQuantizableLinear This mostly required adding docstrings to `forward`, `extra_repr` and `reset_parameters`. Since forward arguments are already part of the module docstrings I just added a very basic docstring. Pull Request resolved: https://github.com/pytorch/pytorch/pull/158491 Approved by: https://github.com/janeyx99
101 lines
3.3 KiB
Python
101 lines
3.3 KiB
Python
import torch.nn.functional as F
|
|
from torch import Tensor
|
|
|
|
from .module import Module
|
|
|
|
|
|
__all__ = ["PairwiseDistance", "CosineSimilarity"]
|
|
|
|
|
|
class PairwiseDistance(Module):
|
|
r"""
|
|
Computes the pairwise distance between input vectors, or between columns of input matrices.
|
|
|
|
Distances are computed using ``p``-norm, with constant ``eps`` added to avoid division by zero
|
|
if ``p`` is negative, i.e.:
|
|
|
|
.. math ::
|
|
\mathrm{dist}\left(x, y\right) = \left\Vert x-y + \epsilon e \right\Vert_p,
|
|
|
|
where :math:`e` is the vector of ones and the ``p``-norm is given by.
|
|
|
|
.. math ::
|
|
\Vert x \Vert _p = \left( \sum_{i=1}^n \vert x_i \vert ^ p \right) ^ {1/p}.
|
|
|
|
Args:
|
|
p (real, optional): the norm degree. Can be negative. Default: 2
|
|
eps (float, optional): Small value to avoid division by zero.
|
|
Default: 1e-6
|
|
keepdim (bool, optional): Determines whether or not to keep the vector dimension.
|
|
Default: False
|
|
Shape:
|
|
- Input1: :math:`(N, D)` or :math:`(D)` where `N = batch dimension` and `D = vector dimension`
|
|
- Input2: :math:`(N, D)` or :math:`(D)`, same shape as the Input1
|
|
- Output: :math:`(N)` or :math:`()` based on input dimension.
|
|
If :attr:`keepdim` is ``True``, then :math:`(N, 1)` or :math:`(1)` based on input dimension.
|
|
|
|
Examples:
|
|
>>> pdist = nn.PairwiseDistance(p=2)
|
|
>>> input1 = torch.randn(100, 128)
|
|
>>> input2 = torch.randn(100, 128)
|
|
>>> output = pdist(input1, input2)
|
|
"""
|
|
|
|
__constants__ = ["norm", "eps", "keepdim"]
|
|
norm: float
|
|
eps: float
|
|
keepdim: bool
|
|
|
|
def __init__(
|
|
self, p: float = 2.0, eps: float = 1e-6, keepdim: bool = False
|
|
) -> None:
|
|
super().__init__()
|
|
self.norm = p
|
|
self.eps = eps
|
|
self.keepdim = keepdim
|
|
|
|
def forward(self, x1: Tensor, x2: Tensor) -> Tensor:
|
|
"""
|
|
Runs the forward pass.
|
|
"""
|
|
return F.pairwise_distance(x1, x2, self.norm, self.eps, self.keepdim)
|
|
|
|
|
|
class CosineSimilarity(Module):
|
|
r"""Returns cosine similarity between :math:`x_1` and :math:`x_2`, computed along `dim`.
|
|
|
|
.. math ::
|
|
\text{similarity} = \dfrac{x_1 \cdot x_2}{\max(\Vert x_1 \Vert _2 \cdot \Vert x_2 \Vert _2, \epsilon)}.
|
|
|
|
Args:
|
|
dim (int, optional): Dimension where cosine similarity is computed. Default: 1
|
|
eps (float, optional): Small value to avoid division by zero.
|
|
Default: 1e-8
|
|
Shape:
|
|
- Input1: :math:`(\ast_1, D, \ast_2)` where D is at position `dim`
|
|
- Input2: :math:`(\ast_1, D, \ast_2)`, same number of dimensions as x1, matching x1 size at dimension `dim`,
|
|
and broadcastable with x1 at other dimensions.
|
|
- Output: :math:`(\ast_1, \ast_2)`
|
|
|
|
Examples:
|
|
>>> input1 = torch.randn(100, 128)
|
|
>>> input2 = torch.randn(100, 128)
|
|
>>> cos = nn.CosineSimilarity(dim=1, eps=1e-6)
|
|
>>> output = cos(input1, input2)
|
|
"""
|
|
|
|
__constants__ = ["dim", "eps"]
|
|
dim: int
|
|
eps: float
|
|
|
|
def __init__(self, dim: int = 1, eps: float = 1e-8) -> None:
|
|
super().__init__()
|
|
self.dim = dim
|
|
self.eps = eps
|
|
|
|
def forward(self, x1: Tensor, x2: Tensor) -> Tensor:
|
|
"""
|
|
Runs the forward pass.
|
|
"""
|
|
return F.cosine_similarity(x1, x2, self.dim, self.eps)
|