diff --git a/docs/source/index.rst b/docs/source/index.rst index 2d6d3eea137..a7afe60bc28 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -108,6 +108,7 @@ Features described in this documentation are classified by release status: torch.random masked torch.nested + size sparse storage torch.testing diff --git a/docs/source/size.rst b/docs/source/size.rst new file mode 100644 index 00000000000..340836e000e --- /dev/null +++ b/docs/source/size.rst @@ -0,0 +1,25 @@ +torch.Size +=================================== + +:class:`torch.Size` is the result type of a call to :func:`torch.Tensor.size`. It describes the size of all dimensions +of the original tensor. As a subclass of :class:`tuple`, it supports common sequence operations like indexing and +length. + + +Example:: + + >>> x = torch.ones(10, 20, 30) + >>> s = x.size() + >>> s + torch.Size([10, 20, 30]) + >>> s[1] + 20 + >>> len(s) + 3 + + + +.. autoclass:: torch.Size + :members: + :undoc-members: + :inherited-members: diff --git a/torch/__init__.py b/torch/__init__.py index 013e5aa832b..846038e3510 100644 --- a/torch/__init__.py +++ b/torch/__init__.py @@ -1624,8 +1624,8 @@ import torch.nn.intrinsic _C._init_names(list(torch._storage_classes)) # attach docstrings to torch and tensor functions -from . import _torch_docs, _tensor_docs, _storage_docs -del _torch_docs, _tensor_docs, _storage_docs +from . import _torch_docs, _tensor_docs, _storage_docs, _size_docs +del _torch_docs, _tensor_docs, _storage_docs, _size_docs def compiled_with_cxx11_abi() -> builtins.bool: diff --git a/torch/_size_docs.py b/torch/_size_docs.py new file mode 100644 index 00000000000..58587be32f1 --- /dev/null +++ b/torch/_size_docs.py @@ -0,0 +1,38 @@ +"""Adds docstrings to torch.Size functions""" + +import torch._C +from torch._C import _add_docstr as add_docstr + + +def add_docstr_all(method, docstr): + add_docstr(getattr(torch._C.Size, method), docstr) + + +add_docstr_all( + "numel", + """ +numel() -> int + +Returns the number of elements a :class:`torch.Tensor` with the given size would contain. + +More formally, for a tensor ``x = tensor.ones(10, 10)`` with size ``s = torch.Size([10, 10])``, +``x.numel() == x.size().numel() == s.numel() == 100`` holds true. + +Example:: + >>> x=torch.ones(10, 10) + >>> s=x.size() + >>> s + torch.Size([10, 10]) + >>> s.numel() + 100 + >>> x.numel() == s.numel() + True + + +.. warning:: + + This function does not return the number of dimensions described by :class:`torch.Size`, but instead the number + of elements a :class:`torch.Tensor` with that size would contain. + +""", +)