Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
"""
import oneflow
from oneflow.framework.docstr.utils import add_docstr
add_docstr(
oneflow.nms,
"""
Performs non-maximum suppression (NMS) on the boxes according
to their intersection-over-union (IoU).
NMS iteratively removes lower scoring boxes which have an
IoU greater than iou_threshold with another (higher scoring)
box.
Args:
boxes (Tensor[N, 4]): boxes to perform NMS on. They
are expected to be in ``(x1, y1, x2, y2)`` format with ``0 <= x1 < x2`` and
``0 <= y1 < y2``.
scores (Tensor[N]): scores for each one of the boxes
iou_threshold (float): discards all overlapping boxes with IoU > iou_threshold
Returns:
Tensor: int64 tensor with the indices of the elements that have been kept by NMS, sorted in decreasing order of scores
""",
)
add_docstr(
oneflow.logical_and,
"""
Computes the element-wise logical AND of the given input tensors.
Zeros are treated as False and nonzeros are treated as True.
Args:
input (oneflow.Tensor): The input Tensor
other (oneflow.Tensor): The Tensor to compute AND with
Returns:
oneflow.Tensor: The output Tensor
For example:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> input1 = flow.tensor(np.array([1, 0, 1]).astype(np.float32), dtype=flow.float32)
>>> input2 = flow.tensor(np.array([1, 1, 0]).astype(np.float32), dtype=flow.float32)
>>> out = flow.logical_and(input1, input2)
>>> out
tensor([ True, False, False], dtype=oneflow.bool)
""",
)
add_docstr(
oneflow._C.cosine_similarity,
r"""
cosine_similarity(x1, x2, dim=1, eps=1e-8) -> Tensor
The documentation is referenced from: https://pytorch.org/docs/stable/generated/torch.nn.functional.cosine_similarity.html#torch.nn.functional.cosine_similarity
Returns cosine similarity between ``x1`` and ``x2``, computed along dim. ``x1`` and ``x2`` must be broadcastable
to a common shape. ``dim`` refers to the dimension in this common shape. Dimension ``dim`` of the output is
squeezed (see :func:`oneflow.squeeze`), resulting in the
output tensor having 1 fewer dimension.
.. math ::
\text{similarity} = \dfrac{x_1 \cdot x_2}{\max(\Vert x_1 \Vert _2 \cdot \Vert x_2 \Vert _2, \epsilon)}
Args:
x1 (Tensor): First input.
x2 (Tensor): Second input.
dim (int, optional): Dimension along which cosine similarity is computed. Default: 1
eps (float, optional): Small value to avoid division by zero.
Default: 1e-8
For examples:
.. code-block:: python
>>> import oneflow as flow
>>> import oneflow.nn.functional as F
>>> input1 = flow.randn(100, 128)
>>> input2 = flow.randn(100, 128)
>>> output = F.cosine_similarity(input1, input2)
""",
)
add_docstr(
oneflow._C.triplet_margin_loss,
r"""
The documentation is referenced from: https://pytorch.org/docs/1.10/generated/torch.nn.functional.triplet_margin_loss.html.
Creates a criterion that measures the triplet loss given an input
tensors :math:`x1`, :math:`x2`, :math:`x3` and a margin with a value greater than :math:`0`.
This is used for measuring a relative similarity between samples. A triplet
is composed by `a`, `p` and `n` (i.e., `anchor`, `positive examples` and `negative
examples` respectively). The shapes of all input tensors should be
:math:`(N, D)`.
The distance swap is described in detail in the paper `Learning shallow
convolutional feature descriptors with triplet losses <http://www.bmva.org/bmvc/2016/papers/paper119/index.html>`__ by
V. Balntas, E. Riba et al.
The loss function for each sample in the mini-batch is:
.. math::
L(a, p, n) = \max \{d(a_i, p_i) - d(a_i, n_i) + {\rm margin}, 0\}
where
.. math::
d(x_i, y_i) = \left\lVert {\bf x}_i - {\bf y}_i \right\rVert_p
Args:
margin (float, optional): Default: :math:`1`.
p (float, optional): The norm degree for pairwise distance. Default: :math:`2.0`.
swap (bool, optional): The distance swap is described in detail in the paper
`Learning shallow convolutional feature descriptors with triplet losses` by
V. Balntas, E. Riba et al. Default: ``False``.
reduction (string, optional): Specifies the reduction to apply to the output:
``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction will be applied,
``'mean'``: the sum of the output will be divided by the number of
elements in the output, ``'sum'``: the output will be summed. Note: :attr:`size_average`
and :attr:`reduce` are in the process of being deprecated, and in the meantime,
specifying either of those two args will override :attr:`reduction`. Default: ``'mean'``
Shape:
- Input: :math:`(N, D)` where :math:`D` is the vector dimension.
- Output: A Tensor of shape :math:`(N)` if :attr:`reduction` is ``'none'``, or a scalar
otherwise.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> triplet_loss = flow.nn.TripletMarginLoss(margin=1.0, p=2)
>>> anchor = np.array([[1, -1, 1],[-1, 1, -1], [1, 1, 1]])
>>> positive = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> negative = np.array([[2, 2, 2], [2, 2, 2], [2, 2, 2]])
>>> output = triplet_loss(flow.Tensor(anchor), flow.Tensor(positive), flow.Tensor(negative))
>>> output
tensor(6.2971, dtype=oneflow.float32)
""",
)
add_docstr(
oneflow.linalg.vector_norm,
"""linalg.vector_norm(input, ord=2, dim=None, keepdim=False, *, dtype=None, out=None) -> Tensor
Computes a vector norm.
Supports input of float, double dtypes.
This function does not necessarily treat multidimensonal attr:`input` as a batch of
vectors, instead:
- If :attr:`dim`\\ `= None`, :attr:`input` will be flattened before the norm is computed.
- If :attr:`dim` is an `int` or a `tuple`, the norm will be computed over these dimensions and the other dimensions will be treated as batch dimensions.
This behavior is for consistency with :func:`flow.linalg.norm`.
:attr:`ord` defines the vector norm that is computed. The following norms are supported:
====================== ========================================================
:attr:`ord` vector norm
====================== ========================================================
`2` (default) `2`-norm (see below)
`inf` `max(abs(x))`
`-inf` `min(abs(x))`
`0` `sum(x != 0)`
other `int` or `float` `sum(abs(x)^{ord})^{(1 / ord)}`
====================== ========================================================
where `inf` refers to `float('inf')`, NumPy's `inf` object, or any equivalent object.
Args:
input (Tensor): tensor, flattened by default, but this behavior can be
controlled using :attr:`dim`.
ord (int, float, inf, -inf, 'fro', 'nuc', optional): order of norm. Default: `2`
dim (int, Tuple[int], optional): dimensions over which to compute
the norm. See above for the behavior when :attr:`dim`\\ `= None`.
Default: `None`
keepdim (bool, optional): If set to `True`, the reduced dimensions are retained
in the result as dimensions with size one. Default: `False`
Returns:
A real-valued tensor.
Examples:
.. code-block:: python
>>> import oneflow as flow
>>> from oneflow import linalg as LA
>>> import numpy as np
>>> a = flow.tensor(np.arange(9, dtype=np.float32) - 4)
>>> a
tensor([-4., -3., -2., -1., 0., 1., 2., 3., 4.], dtype=oneflow.float32)
>>> b = a.reshape(3, 3)
>>> b
tensor([[-4., -3., -2.],
[-1., 0., 1.],
[ 2., 3., 4.]], dtype=oneflow.float32)
>>> LA.vector_norm(a, ord=3.5)
tensor(5.4345, dtype=oneflow.float32)
>>> LA.vector_norm(b, ord=3.5)
tensor(5.4345, dtype=oneflow.float32)
""",
)
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
"""
import oneflow
from oneflow.framework.docstr.utils import add_docstr
add_docstr(
oneflow.nn.Module.to_consistent,
"""
This interface is no longer available, please use :func:`oneflow.nn.Module.to_global` instead.
""",
)
add_docstr(
oneflow.nn.Module.to_global,
"""
Convert the parameters and buffers to global.
It performs the same :func:`oneflow.Tensor.to_global` conversion to each parameter and buffer in this module.
Note:
This method modifies the module in-place.
Both placement and sbp are required if the parameters and buffers of this module are local,
add_docstr(
oneflow.amin,
"""
amin(input, dim, keepdim=False) -> Tensor
This function is equivalent to PyTorch’s amin function.
The documentation is referenced from: https://pytorch.org/docs/stable/generated/torch.amin.html.
Returns the minimum value of each slice of the `input` tensor in the given dimension(s) `dim`.
If `keepdim` is `True`, the output tensor is of the same size as `input` except in the dimension(s) `dim` where it is of size 1. Otherwise, `dim` is squeezed (see :func:`oneflow.squeeze`), resulting in the output tensor having 1 (or `len(dim)`) fewer dimension(s).
Parameters:
input (oneflow.Tensor): the input Tensor.
dim (int, Tuple[int]): the dimension or dimensions to reduce.
keepdim (bool): whether the output tensor has `dim` retained or not.
Example:
.. code-block:: python
>>> import oneflow as flow
>>> x = flow.tensor([[[0,1],[2,3]],[[4,5],[6,7]]])
>>> flow.amin(x, 1)
tensor([[0, 1],
[4, 5]], dtype=oneflow.int64)
>>> flow.amin(x, 0)
tensor([[0, 1],
[2, 3]], dtype=oneflow.int64)
>>> flow.amin(x)
tensor(0, dtype=oneflow.int64)
>>> flow.amin(x, 0, True)
tensor([[[0, 1],
[2, 3]]], dtype=oneflow.int64)
""",
)
add_docstr(
oneflow._C.triplet_margin_loss,
r"""
The documentation is referenced from: https://pytorch.org/docs/stable/generated/torch.nn.functional.triplet_margin_loss.html?highlight=triplet_margin_loss
Creates a criterion that measures the triplet loss given an input
tensors :math:`x1`, :math:`x2`, :math:`x3` and a margin with a value greater than :math:`0`.
This is used for measuring a relative similarity between samples. A triplet
is composed by `a`, `p` and `n` (i.e., `anchor`, `positive examples` and `negative
examples` respectively). The shapes of all input tensors should be
:math:`(N, D)`.
The distance swap is described in detail in the paper `Learning shallow
convolutional feature descriptors with triplet losses <http://www.bmva.org/bmvc/2016/papers/paper119/index.html>`__ by
V. Balntas, E. Riba et al.
The loss function for each sample in the mini-batch is:
.. math::
L(a, p, n) = \max \{d(a_i, p_i) - d(a_i, n_i) + {\rm margin}, 0\}
where
.. math::
d(x_i, y_i) = \left\lVert {\bf x}_i - {\bf y}_i \right\rVert_p
Args:
margin (float, optional): Default: :math:`1`.
p (float, optional): The norm degree for pairwise distance. Default: :math:`2.0`.
swap (bool, optional): The distance swap is described in detail in the paper
`Learning shallow convolutional feature descriptors with triplet losses` by
V. Balntas, E. Riba et al. Default: ``False``.
reduction (string, optional): Specifies the reduction to apply to the output:
``'none'`` | ``'mean'`` | ``'sum'``. ``'none'``: no reduction will be applied,
``'mean'``: the sum of the output will be divided by the number of
elements in the output, ``'sum'``: the output will be summed. Note: :attr:`size_average`
and :attr:`reduce` are in the process of being deprecated, and in the meantime,
specifying either of those two args will override :attr:`reduction`. Default: ``'mean'``
Shape:
- Input: :math:`(N, D)` where :math:`D` is the vector dimension.
- Output: A Tensor of shape :math:`(N)` if :attr:`reduction` is ``'none'``, or a scalar
otherwise.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> triplet_loss = flow.nn.TripletMarginLoss(margin=1.0, p=2)
>>> anchor = np.array([[1, -1, 1],[-1, 1, -1], [1, 1, 1]])
>>> positive = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> negative = np.array([[2, 2, 2], [2, 2, 2], [2, 2, 2]])
>>> output = triplet_loss(flow.Tensor(anchor), flow.Tensor(positive), flow.Tensor(negative))
>>> output
tensor(6.2971, dtype=oneflow.float32)
""",
)
add_docstr(
oneflow.expand,
"""
oneflow.expand(input, *sizes) -> Tensor,
This operator expand the input tensor to a larger size.
Passing -1 as the size for a dimension means not changing the size of that dimension.
Tensor can be also expanded to a larger number of dimensions and the new ones will be appended at the front.
For the new dimensions, the size cannot be set to -1.
Args:
input (oneflow.Tensor): the input Tensor.
*sizes (oneflow.Size or int): The desired expanded size.
Returns:
oneflow.Tensor: The result Tensor.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> x = np.array([[[[0, 1]],
... [[2, 3]],
... [[4, 5]]]]).astype(np.int32)
>>> input = flow.Tensor(x)
>>> input.shape
oneflow.Size([1, 3, 1, 2])
>>> out = input.expand(1, 3, 2, 2)
>>> out.shape
oneflow.Size([1, 3, 2, 2])
""",
)
add_docstr(
oneflow.index_select,
"""
input.index_select(dim, index) -> Tensor
The interface is consistent with PyTorch.
The documentation is referenced from: https://pytorch-cn.readthedocs.io/zh/latest/package_references/torch/#torchindex_select
Select values along an axis specified by `dim`.
:attr:`index` must be an Int32 Tensor with 1-D.
:attr:`dim` must be in the range of input Dimensions.
value of :attr:`index` must be in the range of the dim-th of input.
Note that ``input`` and ``index`` do not broadcast against each other.
Args:
input (Tensor): the source tensor
dim (int): the axis along which to index
index (Tensor): the 1-D tensor containing the indices to index
For example:
.. code-block:: python
>>> import oneflow as flow
>>> input = flow.tensor([[1,2,3],[4,5,6]], dtype=flow.int32)
>>> input
tensor([[1, 2, 3],
[4, 5, 6]], dtype=oneflow.int32)
>>> index = flow.tensor([0,1], dtype=flow.int32)
>>> output = flow.index_select(input, 1, index)
>>> output
tensor([[1, 2],
[4, 5]], dtype=oneflow.int32)
>>> output = input.index_select(1, index)
>>> output
tensor([[1, 2],
[4, 5]], dtype=oneflow.int32)
""",
)
add_docstr(
oneflow.repeat,
"""
repeat(input, sizes) -> Tensor
This operator repeat the input tensor to a larger size along the specified dimensions.
Args:
input (oneflow.Tensor): The input Tensor.
sizes (flow.Shape or List): The number of times to repeat this tensor along each dimension.
Returns:
oneflow.Tensor: The result Tensor.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> np_arr = np.random.randn(5, 3, 6, 9).astype(np.float32)
>>> input = flow.Tensor(np_arr)
>>> out = input.repeat(1, 1, 2, 2)
>>> out.shape
oneflow.Size([5, 3, 12, 18])
>>> out = input.repeat(2, 1, 1, 2, 2)
>>> out.shape
oneflow.Size([2, 5, 3, 12, 18])
""",
)
add_docstr(
oneflow.sort,
"""Sorts the elements of the input tensor along a given dimension in ascending order by value.
Args:
input (oneflow.Tensor): The input Tensor.
dim (int, optional): dimension to be sorted. Defaults to the last dim (-1).
descending (bool, optional): controls the sorting order (ascending or descending).
Returns:
Tuple(oneflow.Tensor, oneflow.Tensor(dtype=int32)): A tuple of (values, indices), where
where the values are the sorted values and the indices are the indices of the elements
in the original input tensor.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> x = np.array([[1, 3, 8, 7, 2], [1, 9, 4, 3, 2]], dtype=np.float32)
>>> input = flow.Tensor(x)
>>> (values, indices) = flow.sort(input)
>>> values
tensor([[1., 2., 3., 7., 8.],
[1., 2., 3., 4., 9.]], dtype=oneflow.float32)
>>> indices
tensor([[0, 4, 1, 3, 2],
[0, 4, 3, 2, 1]], dtype=oneflow.int32)
>>> (values, indices) = flow.sort(input, descending=True)
>>> values
tensor([[8., 7., 3., 2., 1.],
[9., 4., 3., 2., 1.]], dtype=oneflow.float32)
>>> indices
tensor([[2, 3, 1, 4, 0],
[1, 2, 3, 4, 0]], dtype=oneflow.int32)
>>> (values, indices) = flow.sort(input, dim=0)
>>> values
tensor([[1., 3., 4., 3., 2.],
[1., 9., 8., 7., 2.]], dtype=oneflow.float32)
>>> indices
tensor([[0, 0, 1, 1, 0],
[1, 1, 0, 0, 1]], dtype=oneflow.int32)
""",
)
add_docstr(
oneflow.decode_onerec,
r"""
(Tensor input, String key, DataType dtype, Shape shape, Bool is_dynamic=False, Shape reshape=None, Shape batch_padding=None)
decode_onerec(input:Tensor, key:str, dtype, shape, is_dynamic=False, reshape=None, batch_padding=None) -> Tensor
Decode a tensor from input which should be generated before by oneflow.nn.OneRecReader.
Args:
input: (Tensor): The tensor generated by oneflow.nn.OneRecReader before.
key(str): The field name of the tensor to be decode
shape(bool): The shape of the tensor to be decode
is_dynamic(bool): The tensor shape is dynamic or not
reshape(tuple): Set it if you want to reshape the tensor
batch_padding(tuple): Set it if batch padding is needed
For example:
.. code-block:: python
import oneflow as flow
files = ['file01.onerec', 'file02.onerec']
# read onerec dataset form files
reader = flow.nn.OneRecReader(files, 10, True, "batch")
readdata = reader()
# decode
labels = flow.decode_onerec(readdata, key="labels", dtype=flow.int32, shape=(1,))
dense_fields = flow.decode_onerec(readdata, key="dense_fields", dtype=flow.float, shape=(13,))
""",
)
add_docstr(
oneflow.searchsorted,
"""
searchsorted() -> oneflow.Tensor
The documentation is referenced from: https://pytorch.org/docs/1.10/generated/torch.searchsorted.html?highlight=searchsorted
Find the indices from the innermost dimension of sorted_sequence such that, if the corresponding values
in values were inserted before the indices, the order of the corresponding innermost dimension within
sorted_sequence would be preserved. Return a new tensor with the same size as values. If right is False
(default), then the left boundary of sorted_sequence is closed. More formally, the returned index
satisfies the following rules:
================= ========= ==========================================================================
sorted_sequence right returned index satisfies
================= ========= ==========================================================================
1-D False sorted_sequence[i-1] < values[m][n]...[l][x] <= sorted_sequence[i]
1-D True sorted_sequence[i-1] <= values[m][n]...[l][x] < sorted_sequence[i]
N-D False sorted_sequence[m][n]...[l][i-1] < values[m][n]...[l][x]
<= sorted_sequence[m][n]...[l][i]
N-D True sorted_sequence[m][n]...[l][i-1] <= values[m][n]...[l][x]
sorted_sequence[m][n]...[l][i]
================= ========= ==========================================================================
Args:
sorted_sequence (Tensor): N-D or 1-D tensor, containing monotonically increasing sequence on the
innermost dimension.
values (Tensor or Scalar): N-D tensor or a Scalar containing the search value(s).
out_int32 (bool optional): indicate the output data type. torch.int32 if True, torch.int64 otherwise.
Default value is False, i.e. default output data type is torch.int64.
right (bool optional): if False, return the first suitable location that is found. If True, return the
last such index. If no suitable index found, return 0 for non-numerical value
(eg. nan, inf) or the size of innermost dimension within sorted_sequence (one
pass the last index of the innermost dimension). In other words, if False, gets
the lower bound index for each value in values on the corresponding innermost
dimension of the sorted_sequence. If True, gets the upper bound index instead.
Default value is False.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> sorted_sequence = flow.tensor([[1, 3, 5, 7, 9], [2, 4, 6, 8, 10]])
>>> sorted_sequence
tensor([[ 1, 3, 5, 7, 9],
[ 2, 4, 6, 8, 10]], dtype=oneflow.int64)
>>> values = flow.tensor([[3, 6, 9], [3, 6, 9]])
>>> values
tensor([[3, 6, 9],
[3, 6, 9]], dtype=oneflow.int64)
>>> flow.searchsorted(sorted_sequence, values)
tensor([[1, 3, 4],
[1, 2, 4]], dtype=oneflow.int64)
>>> flow.searchsorted(sorted_sequence, values, right=True)
tensor([[2, 3, 5],
[1, 3, 4]], dtype=oneflow.int64)
>>> sorted_sequence_1d = flow.tensor([1, 3, 5, 7, 9])
>>> sorted_sequence_1d
tensor([1, 3, 5, 7, 9], dtype=oneflow.int64)
>>> flow.searchsorted(sorted_sequence_1d, values)
tensor([[1, 3, 4],
[1, 3, 4]], dtype=oneflow.int64)
""",
)
add_docstr(
oneflow.where,
"""Return a tensor of elements selected from either :attr:`x` or :attr:`y`, depending on :attr:`condition`.
If the element in condition is larger than 0,
it will take the `x` element, else it will take the `y` element
.. note::
If :attr:`x` is None and :attr:`y` is None, flow.where(condition) is
identical to flow.nonzero(condition, as_tuple=True).
The tensors :attr:`condition`, :attr:`x`, :attr:`y` must be broadcastable.
Args:
condition (IntTensor): When 1 (nonzero), yield x, otherwise yield y
x (Tensor or Scalar): value (if :attr:x is a scalar) or values selected at indices
where :attr:`condition` is True
y (Tensor or Scalar): value (if :attr:x is a scalar) or values selected at indices
where :attr:`condition` is False
Returns:
Tensor: A tensor of shape equal to the broadcasted shape of :attr:`condition`, :attr:`x`, :attr:`y`
For example:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> x = flow.tensor(
... np.array([[-0.4620, 0.3139], [0.3898, -0.7197], [0.0478, -0.1657]]),
... dtype=flow.float32,
... )
>>> y = flow.tensor(np.ones(shape=(3, 2)), dtype=flow.float32)
>>> condition = flow.tensor(np.array([[0, 1], [1, 0], [1, 0]]), dtype=flow.int32)
>>> out = condition.where(x, y)
>>> out #doctest: +ELLIPSIS
tensor([[1.0000, 0.3139],
...
[0.0478, 1.0000]], dtype=oneflow.float32)
""",
)
add_docstr(
oneflow._C.pad,
r"""
Pads tensor.
Padding size:
The padding size by which to pad some dimensions of :attr:`input`
are described starting from the last dimension and moving forward.
:math:`\left\lfloor\frac{\text{len(pad)}}{2}\right\rfloor` dimensions
of ``input`` will be padded.
For example, to pad only the last dimension of the input tensor, then
:attr:`pad` has the form
:math:`(\text{padding_left}, \text{padding_right})`;
to pad the last 2 dimensions of the input tensor, then use
:math:`(\text{padding_left}, \text{padding_right},`
:math:`\text{padding_top}, \text{padding_bottom})`;
to pad the last 3 dimensions, use
:math:`(\text{padding_left}, \text{padding_right},`
:math:`\text{padding_top}, \text{padding_bottom}`
:math:`\text{padding_front}, \text{padding_back})`.
Padding mode:
See :class:`oneflow.nn.ConstantPad2d`, :class:`oneflow.nn.ReflectionPad2d`, and
:class:`oneflow.nn.ReplicationPad2d` for concrete examples on how each of the
padding modes works. Constant padding is implemented for arbitrary dimensions.
Replicate padding is implemented for padding the last 3 dimensions of 5D input
tensor, or the last 2 dimensions of 4D input tensor, or the last dimension of
3D input tensor. Reflect padding is only implemented for padding the last 2
dimensions of 4D input tensor, or the last dimension of 3D input tensor.
Args:
input (Tensor): N-dimensional tensor
pad (tuple): m-elements tuple, where
:math:`\frac{m}{2} \leq` input dimensions and :math:`m` is even.
mode: ``'constant'``, ``'reflect'``, ``'replicate'`` or ``'circular'``.
Default: ``'constant'``
value: fill value for ``'constant'`` padding. Default: ``0``
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> pad = [2, 2, 1, 1]
>>> input = flow.tensor(np.arange(18).reshape((1, 2, 3, 3)).astype(np.float32))
>>> output = flow.nn.functional.pad(input, pad, mode = "replicate")
>>> output.shape
oneflow.Size([1, 2, 5, 7])
>>> output
tensor([[[[ 0., 0., 0., 1., 2., 2., 2.],
[ 0., 0., 0., 1., 2., 2., 2.],
[ 3., 3., 3., 4., 5., 5., 5.],
[ 6., 6., 6., 7., 8., 8., 8.],
[ 6., 6., 6., 7., 8., 8., 8.]],
<BLANKLINE>
[[ 9., 9., 9., 10., 11., 11., 11.],
[ 9., 9., 9., 10., 11., 11., 11.],
[12., 12., 12., 13., 14., 14., 14.],
[15., 15., 15., 16., 17., 17., 17.],
[15., 15., 15., 16., 17., 17., 17.]]]], dtype=oneflow.float32)
See :class:`oneflow.nn.ConstantPad2d`, :class:`oneflow.nn.ReflectionPad2d`, and :class:`oneflow.nn.ReplicationPad2d` for concrete examples on how each of the padding modes works.
""",
)
add_docstr(
oneflow._C.dropout,
"""
dropout(x: Tensor, p: float = 0.5, training: bool = True, generator :Generator = None, *, addend: Tensor) -> Tensor
The documentation is referenced from:
https://pytorch.org/docs/stable/generated/torch.nn.functional.dropout.html
During training, randomly zeroes some of the elements of the input
tensor with probability :attr:`p` using samples from a Bernoulli
distribution.
Args:
x(Tensor): A Tensor which will be applyed dropout.
p(float): probability of an element to be zeroed. Default: 0.5
training(bool): If is True it will apply dropout. Default: True
generator(Generator, optional): A pseudorandom number generator for sampling
addend(Tensor, optional): A Tensor add in result after dropout, it can be used in model's residual connection structure. Default: None
Shape:
- Input: :math:`(*)`. Input can be of any shape
- Output: :math:`(*)`. Output is of the same shape as input
For example:
Example 1:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> arr = np.array(
... [
... [-0.7797, 0.2264, 0.2458, 0.4163],
... [0.4299, 0.3626, -0.4892, 0.4141],
... [-1.4115, 1.2183, -0.5503, 0.6520],
... ]
... )
>>> x = flow.tensor(arr, dtype=flow.float32)
>>> y = flow.nn.functional.dropout(x, p=0)
>>> arr = np.array(
... [
... [-0.7797, 0.2264, 0.2458, 0.4163],
... [0.4299, 0.3626, -0.4892, 0.4141],
... [-1.4115, 1.2183, -0.5503, 0.6520],
... ]
... )
>>> x = flow.tensor(arr, dtype=flow.float32)
>>> generator = flow.Generator()
>>> y = flow.nn.functional.dropout(x, p=0.5, generator=generator)
Example 2:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> arr = np.array(
... [
... [-0.7797, 0.2264, 0.2458, 0.4163],
... [0.4299, 0.3626, -0.4892, 0.4141],
... [-1.4115, 1.2183, -0.5503, 0.6520],
... ]
... )
>>> x = flow.tensor(arr, dtype=flow.float32)
>>> addend = flow.ones((3, 4), dtype=flow.float32)
>>> y = flow.nn.functional.dropout(x, p=0, addend=addend)
>>> y #doctest: +ELLIPSIS
tensor([[ 0.2203, 1.2264, 1.2458, 1.4163],
[ 1.4299, 1.3626, 0.5108, 1.4141],
[-0.4115, 2.2183, 0.4497, 1.6520]], dtype=oneflow.float32)
See :class:`~oneflow.nn.Dropout` for details.
""",
)
add_docstr(
oneflow.diagonal,
r"""
oneflow.diagonal(input, offset, dim1, dim2) -> Tensor
Returns a partial view of input with the its diagonal elements with respect to dim1 and dim2
appended as a dimension at the end of the shape.
Args:
input (Tensor): the input tensor.Must be at least 2-dimensional.
offset (Optional[int], 0): which diagonal to consider. Default: 0 (main diagonal)
dim1 (Optional[int], 0): first dimension with respect to which to take diagonal. Default: 0
dim2 (Optional[int], 1): second dimension with respect to which to take diagonal. Default: 1
Returns:
oneflow.Tensor: the output Tensor.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> input = flow.randn(2, 3, 4)
>>> output = flow.diagonal(input, offset=1, dim1=1, dim2=0)
>>> output.shape
oneflow.Size([4, 1])
""",
)
add_docstr(
oneflow.chunk,
"""Splits a tensor into a specific number of chunks. Each chunk is a view of the input tensor. Last chunk will be bigger if the tensor size along the given dimension dim is not divisible by chunks.
Args:
input (oneflow.Tensor): The tensor to split.
chunks (int): Number of chunks to return.
dim (int): Dimension along which to split the tensor.
Returns:
List of Tensors.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> np_arr = np.random.randn(5, 3, 6, 9).astype(np.float32)
>>> input = flow.Tensor(np_arr)
>>> of_out = []
>>> of_out = flow.chunk(input, chunks=3, dim=2)
>>> chunks = 3
>>> of_out_shape = []
>>> for i in range(0, chunks):
... of_out_shape.append(of_out[i].numpy().shape)
>>> of_out_shape
[(5, 3, 2, 9), (5, 3, 2, 9), (5, 3, 2, 9)]
>>> np_arr = np.random.randn(5, 3, 6, 9).astype(np.float32)
>>> input = flow.Tensor(np_arr)
>>> of_out = []
>>> of_out = flow.chunk(input, chunks=4, dim=3)
>>> chunks = 4
>>> of_out_shape = []
>>> for i in range(0, chunks):
... of_out_shape.append(of_out[i].numpy().shape)
>>> of_out_shape
[(5, 3, 6, 2), (5, 3, 6, 2), (5, 3, 6, 2), (5, 3, 6, 3)]
""",
)
add_docstr(
oneflow._C.conv1d,
r"""
conv1d(input, weight, bias=None, stride=[1], padding=[0], dilation=[1], groups=1) -> Tensor
The documentation is referenced from: https://pytorch.org/docs/stable/generated/torch.nn.functional.conv1d.html?highlight=conv1d
Applies a 1D convolution over an input signal composed of several input
planes.
See :class:`~oneflow.nn.Conv1d` for details and output shape.
Args:
input: quantized input tensor of shape :math:`(\text{minibatch} , \text{in_channels} , iW)`
weight: quantized filters of shape :math:`(\text{out_channels} , \frac{\text{in_channels}}{\text{groups}} , iW)`
bias: **non-quantized** bias tensor of shape :math:`(\text{out_channels})`. The tensor type must be `flow.float`.
stride: the stride of the convolving kernel. Can be a single number or a
tuple `(sW,)`. Default: 1
padding: implicit paddings on both sides of the input. Can be a
single number or a tuple `(padW,)`. Default: 0
dilation: the spacing between kernel elements. Can be a single number or
a tuple `(dW,)`. Default: 1
groups: split input into groups, :math:`\text{in_channels}` should be divisible by the
number of groups. Default: 1
For examples:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> input = flow.tensor(np.random.randn(33, 16, 30), dtype=flow.float32)
>>> filters = flow.tensor(np.random.randn(20, 16, 5), dtype=flow.float32)
>>> out = flow._C.conv1d(input, filters,stride=[1], padding=[0], dilation=[1], channel_pos="channels_first")
""",
)
"""
import oneflow
from oneflow.framework.docstr.utils import add_docstr
add_docstr(
oneflow.bmm,
"""
Performs a batch matrix-matrix product of matrices stored in input and mat2.
`input` and `mat2` must be 3-D tensors each containing the same number of matrices.
If input is a (b x n x m) tensor, mat2 is a (b x m x p) tensor, out will be a (b x n x p) tensor.
Args:
input(oneflow.Tensor): the first batch of matrices to be multiplied
mat2(oneflow.Tensor): the second batch of matrices to be multiplied
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> input1 = flow.randn(10, 3, 4)
>>> input2 = flow.randn(10, 4, 5)
>>> of_out = flow.bmm(input1, input2)
>>> of_out.shape
oneflow.Size([10, 3, 5])
""",
)
See the License for the specific language governing permissions and
limitations under the License.
"""
import oneflow
from oneflow.framework.docstr.utils import add_docstr
add_docstr(
oneflow.isnan,
"""
Returns a new tensor with boolean elements representing if each element of input is NaN or not.
Args:
input(Tensor): the input tensor.
Returns:
A boolean tensor that is True where input is NaN and False elsewhere.
Example::
>>> import oneflow as flow
>>> flow.isnan(flow.tensor([1, float('nan'), 2]))
tensor([False, True, False], dtype=oneflow.bool)
""",
)
add_docstr(
oneflow.isinf,
"""
Tests if each element of input is infinite (positive or negative infinity) or not.
add_docstr(
oneflow.amax,
"""
oneflow.amax(input, dim=None, keepdim=False) -> Tensor
This function is equivalent to PyTorch’s amax function. It returns the maximum along a dimension.
Args:
input (oneflow.Tensor): the input Tensor.
dim (int or List of int, optional): the dimension or the dimensions to reduce. Dim is None by default.
keepdim (bool, optional): whether to retain the dimension. keepdim is False by default.
Returns:
oneflow.Tensor: Maximum of the input tensor
For example:
.. code-block:: python
>>> import oneflow as flow
>>> x = flow.tensor([[[0,1],[2,3]],[[4,5],[6,7]]])
>>> flow.amax(x, 1)
tensor([[2, 3],
[6, 7]], dtype=oneflow.int64)
>>> flow.amax(x, 0)
tensor([[4, 5],
[6, 7]], dtype=oneflow.int64)
>>> flow.amax(x)
tensor(7, dtype=oneflow.int64)
>>> flow.amax(x, 0, True)
tensor([[[4, 5],
[6, 7]]], dtype=oneflow.int64)
""",
)
add_docstr(
oneflow._C.conv1d,
r"""
conv1d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor
The documentation is referenced from: https://pytorch.org/docs/1.10/generated/torch.nn.functional.conv1d.html.
Applies a 1D convolution over an input signal composed of several input
planes.
See :class:`~oneflow.nn.Conv1d` for details and output shape.
Args:
input: input tensor of shape :math:`(\text{minibatch} , \text{in_channels} , iW)`
weight: filters of shape :math:`(\text{out_channels} , \frac{\text{in_channels}}{\text{groups}} , iW)`
bias: optional bias of shape :math:`(\text{out_channels})`. Default: None.
stride: the stride of the convolving kernel. Can be a single number or a
tuple `(sW,)`. Default: 1
padding: implicit paddings on both sides of the input. Can be a
single number or a tuple `(padW,)`. Default: 0
dilation: the spacing between kernel elements. Can be a single number or
a tuple `(dW,)`. Default: 1
groups: split input into groups, :math:`\text{in_channels}` should be divisible by the
number of groups. Default: 1
For examples:
.. code-block:: python
>>> import oneflow as flow
>>> import oneflow.nn.functional as F
>>> inputs = flow.randn(33, 16, 30)
>>> filters = flow.randn(20, 16, 5)
>>> outputs = F.conv1d(inputs, filters)
""",
)
add_docstr(
oneflow.roc_auc_score,
"""
oneflow.roc_auc_score(label, pred) -> Tensor
Compute Area Under the Receiver Operating Characteristic Curve (ROC AUC) from prediction scores.
Note: Currently this implementation can only be used on CPU.
Args:
label (Tensor[N, 1]): True lable of the samples
pred (Tensor[N, 1]): Predicted probability value to be true
Returns:
Tensor[1, ]: float32 tensor of auc score
For example:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> label = flow.Tensor([0, 0, 1, 1])
>>> pred = flow.Tensor([0.1, 0.4, 0.35, 0.8])
>>> score = flow.roc_auc_score(label, pred)
>>> score
tensor([0.7500], dtype=oneflow.float32)
""",
)
add_docstr(
oneflow._C.prelu,
"""
prelu(x: Tensor, alpha: Tensor) -> Tensor
Applies the element-wise function:
.. math::
prelu(x) = max(0,x) + alpha * min(0,x)
For example:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> x = flow.tensor(np.asarray([[[[1, -2], [3, 4]]]]), dtype=flow.float32)
>>> alpha = flow.nn.Parameter(flow.tensor([1], dtype=flow.float32).fill_(0.25))
>>> flow.nn.functional.prelu(x, alpha)
tensor([[[[ 1.0000, -0.5000],
[ 3.0000, 4.0000]]]], dtype=oneflow.float32,
grad_fn=<prelu_backward>)
See
:class:`~oneflow.nn.PReLU` for more details.
""",
)
add_docstr(
oneflow.index_select,
"""
input.index_select(dim, index) -> Tensor
The interface is consistent with PyTorch.
The documentation is referenced from: https://pytorch.org/docs/1.11/generated/torch.index_select.html#torch.index_select
Select values along an axis specified by `dim`.
:attr:`index` must be an Int32 Tensor with 1-D.
:attr:`dim` must be in the range of input Dimensions.
value of :attr:`index` must be in the range of the dim-th of input.
Note that ``input`` and ``index`` do not broadcast against each other.
Args:
input (Tensor): the source tensor
dim (int): the axis along which to index
index (Tensor): the 1-D tensor containing the indices to index
For example:
.. code-block:: python
>>> import oneflow as flow
>>> input = flow.tensor([[1,2,3],[4,5,6]], dtype=flow.int32)
>>> input
tensor([[1, 2, 3],
[4, 5, 6]], dtype=oneflow.int32)
>>> index = flow.tensor([0,1], dtype=flow.int32)
>>> output = flow.index_select(input, 1, index)
>>> output
tensor([[1, 2],
[4, 5]], dtype=oneflow.int32)
>>> output = input.index_select(1, index)
>>> output
tensor([[1, 2],
[4, 5]], dtype=oneflow.int32)
..
Feature Stage of Operator [index_select].
- Maintainer List [@QiangX-man, @hjchen2, @strint]
- Current Stage [ ]
- Alpha Stage Check List [ ]
- API(Compatible with PyTorch 1.11, anything incompatible must be noted in API Doc.)[Yes]
- Doc(API Doc must be provided and showed normally on the web page.)[Yes]
- Functionality and its' Test [ ]
- Functionality is highly compatiable with PyTorch 1.11. [Yes]
- eager local [Yes] [@QiangX-man, @hjchen2]
- forward [Yes]
- backward [Yes]
- gpu [Yes]
- cpu [Yes]
- graph local [ ] [@BBuf, @strint, @hjchen2]
- forward [Yes]
- backward [ ]
- gpu [Yes]
- cpu [Yes]
- Exception Handling
- Exception Message and Hint must be provided [ ]
- Beta Stage Check List [ ]
- API(High compatibility with PyTorch 1.11, shouldn't have anything incompatible for a naive reason.)[ ]
- Doc(Same standard as Alpha Stage)[ ]
- Functionality and its' Test [ ]
- eager global [ ]
- forward [ ]
- backward [ ]
- gpu [ ]
- cpu [ ]
- graph gloal [ ]
- forward [ ]
- backward [ ]
- gpu [ ]
- cpu [ ]
- Performance and Scalability(Must be evaluated.)[ ]
- CUDA kernel [ ]
- CPU kernel [ ]
- N nodes M devices [ ]
- Exception Handling [ ]
- Exception Message and Hint must be provided [ ]
- Try you best to do Exception Recovery [ ]
- Stable Stage Check List [ ]
- API(Same standard as Beta Stage)[ ]
- Doc(Same standard as Beta Stage)[ ]
- Functionality and its' Test [ ]
- fp16 and AMP [ ]
- NHWC [ ]
- Performance and Scalability(Must be evaluated.)[ ]
- Exception Handling [ ]
""",
)
add_docstr(
oneflow.flip,
"""
flip(input, dims) -> Tensor
Reverse the order of a n-D tensor along given axis in dims.
.. note::
`flow.flip` makes a copy of :attr:`input`'s data. This is different from NumPy's `np.flip`,
which returns a view in constant time. Since copying a tensor's data is more work than viewing that data,
`flow.flip` is expected to be slower than `np.flip`.
Args:
input (Tensor): the input tensor
dims (a list or tuple): axis to flip on
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> np_arr = np.arange(0, 8).reshape((2, 2, 2)).astype(np.float32)
>>> input = flow.Tensor(np_arr)
>>> input.shape
oneflow.Size([2, 2, 2])
>>> out = flow.flip(input, [0, 1])
>>> out
tensor([[[6., 7.],
[4., 5.]],
<BLANKLINE>
[[2., 3.],
[0., 1.]]], dtype=oneflow.float32)
""",
)
add_docstr(
oneflow.bernoulli,
"""
bernoulli(x, *, generator=None, out=None)
This operator returns a Tensor with binaray random numbers (0 / 1) from a Bernoulli distribution.
Args:
x (Tensor): the input tensor of probability values for the Bernoulli distribution
generator (Generator, optional): a pseudorandom number generator for sampling
out (Tensor, optional): the output tensor.
Shape:
- Input: :math:`(*)`. Input can be of any shape
- Output: :math:`(*)`. Output is of the same shape as input
For example:
.. code-block:: python
>>> import numpy as np
>>> import oneflow as flow
>>> arr = np.array(
... [
... [1.0, 1.0, 1.0],
... [1.0, 1.0, 1.0],
... [1.0, 1.0, 1.0],
... ]
... )
>>> x = flow.tensor(arr, dtype=flow.float32)
>>> y = flow.bernoulli(x)
>>> y
tensor([[1., 1., 1.],
[1., 1., 1.],
[1., 1., 1.]], dtype=oneflow.float32)
""",
)
import oneflow
from oneflow.framework.docstr.utils import add_docstr
add_docstr(
oneflow.cast,
"""
The operation takes input tensor `x` and casts it to the output with `dtype`
Args:
x (oneflow.Tensor): A Tensor
dtype (flow.dtype): Data type of the output tensor
Returns:
oneflow.Tensor: A Tensor with specific dtype.
For example:
.. code-block:: python
>>> import oneflow as flow
>>> import numpy as np
>>> np_arr = np.random.randn(2, 3, 4, 5).astype(np.float32)
>>> input = flow.tensor(np_arr, dtype=flow.float32)
>>> output = flow.cast(input, flow.int8)
>>> np.array_equal(output.numpy(), np_arr.astype(np.int8))
True
""",
)
