torch.nn.modules.sparse 的源代码

```html

from typing import Optional

import torch
from torch import Tensor
from torch.nn.parameter import Parameter

from .module import Module
from .. import functional as F
from .. import init

__all__ = ['Embedding', 'EmbeddingBag']

class Embedding(Module):
    r"""一个简单的查找表，用于存储固定字典和大小的嵌入。

    该模块通常用于存储词嵌入并通过索引检索它们。
    模块的输入是一个索引列表，输出是对应的词嵌入。

    参数:
        num_embeddings (int): 嵌入字典的大小
        embedding_dim (int): 每个嵌入向量的大小
        padding_idx (int, 可选): 如果指定，:attr:`padding_idx`处的条目不会对梯度做出贡献；
                                     因此，:attr:`padding_idx`处的嵌入向量在训练期间不会更新，
                                     即它保持为固定的“填充”。对于新构造的嵌入，
                                     :attr:`padding_idx`处的嵌入向量将默认为全零，
                                     但可以更新为另一个值以用作填充向量。
        max_norm (float, 可选): 如果给定，范数大于:attr:`max_norm`的每个嵌入向量
                                    将被重新归一化为范数:attr:`max_norm`。
        norm_type (float, 可选): 用于:attr:`max_norm`选项的p范数的p值。默认 ``2``。
        scale_grad_by_freq (bool, 可选): 如果给定，这将按小批量中单词的频率的倒数缩放梯度。默认 ``False``。
        sparse (bool, 可选): 如果 ``True``，关于:attr:`weight`矩阵的梯度将是一个稀疏张量。
                                 有关稀疏梯度的更多详细信息，请参见注释。

    属性:
        weight (Tensor): 模块的可学习权重，形状为 (num_embeddings, embedding_dim)
                         从 :math:`\mathcal{N}(0, 1)` 初始化

    形状:
        - 输入: :math:`(*)`，包含要提取索引的任意形状的IntTensor或LongTensor
        - 输出: :math:`(*, H)`，其中 `*` 是输入形状，:math:`H=\text{embedding\_dim}`

    .. 注意::
        请记住，只有有限数量的优化器支持
        稀疏梯度：目前是 :class:`optim.SGD` (`CUDA` 和 `CPU`)，
        :class:`optim.SparseAdam` (`CUDA` 和 `CPU`) 和 :class:`optim.Adagrad` (`CPU`)

    .. 注意::
        当 :attr:`max_norm` 不是 ``None`` 时，:class:`Embedding` 的前向方法将就地修改
        :attr:`weight` 张量。由于用于梯度计算的张量不能
        就地修改，因此在调用 :class:`Embedding` 的前向方法之前
        对 ``Embedding.weight`` 执行可微操作需要克隆 ``Embedding.weight``，
        当 :attr:`max_norm` 不是 ``None`` 时。例如::

            n, d, m = 3, 5, 7
            embedding = nn.Embedding(n, d, max_norm=True)
            W = torch.randn((m, d), requires_grad=True)
            idx = torch.tensor([1, 2])
            a = embedding.weight.clone() @ W.t()  # 必须克隆权重以使其可微
            b = embedding(idx) @ W.t()  # 就地修改权重
            out = (a.unsqueeze(0) + b.unsqueeze(1))
            loss = out.sigmoid().prod()
            loss.backward()

    示例::

        >>> # 包含10个大小为3的张量的嵌入模块
        >>> embedding = nn.Embedding(10, 3)
        >>> # 一批2个样本，每个样本有4个索引
        >>> input = torch.LongTensor([[1, 2, 4, 5], [4, 3, 2, 9]])
        >>> # xdoctest: +IGNORE_WANT("非确定性")
        >>> embedding(input)
        tensor([[[-0.0251, -1.6902,  0.7172],
                 [-0.6431,  0.0748,  0.6969],
                 [ 1.4970,  1.3448, -0.9685],
                 [-0.3677, -2.7265, -0.1685]],

                [[ 1.4970,  1.3448, -0.9685],
                 [ 0.4362, -0.4004,  0.9400],
                 [-0.6431,  0.0748,  0.6969],
                 [ 0.9124, -2.3616,  1.1151]]])


        >>> # 使用padding_idx的示例
        >>> embedding = nn.Embedding(10, 3, padding_idx=0)
        >>> input = torch.LongTensor([[0, 2, 0, 5]])
        >>> embedding(input)
        tensor([[[ 0.0000,  0.0000,  0.0000],
                 [ 0.1535, -2.0309,  0.9315],
                 [ 0.0000,  0.0000,  0.0000],
                 [-0.1655,  0.9897,  0.0635]]])

        >>> # 更改 `pad` 向量的示例
        >>> padding_idx = 0
        >>> embedding = nn.Embedding(3, 3, padding_idx=padding_idx)
        >>> embedding.weight
        Parameter containing:
        tensor([[ 0.0000,  0.0000,  0.0000],
                [-0.7895, -0.7089, -0.0364],
                [ 0.6778,  0.5803,  0.2678]], requires_grad=True)
        >>> with torch.no_grad():
        ...     embedding.weight[padding_idx] = torch.ones(3)
        >>> embedding.weight
        Parameter containing:
        tensor([[ 1.0000,  1.0000,  1.0000],
                [-0.7895, -0.7089, -0.0364],
                [ 0.6778,  0.5803,  0.2678]], requires_grad=True)
    """

    __constants__ = ['num_embeddings', 'embedding_dim', 'padding_idx', 'max_norm',
                     'norm_type', 'scale_grad_by_freq', 'sparse']

    num_embeddings: int
    embedding_dim: int
    padding_idx: Optional[int]
    max_norm: Optional[float]
    norm_type: float
    scale_grad_by_freq: bool
    weight: Tensor
    freeze: bool
    sparse: bool

    def __init__(self, num_embeddings: int, embedding_dim: int, padding_idx: Optional[int] = None,
                 max_norm: Optional[float] = None, norm_type: float = 2., scale_grad_by_freq: bool = False,
                 sparse: bool = False, _weight: Optional[Tensor] = None, _freeze: bool = False,
                 device=None, dtype=None) -> None:
        <span