diff --git a/docker/ci/test/requirements.txt b/docker/ci/test/requirements.txt index b3c11d21932..f05e7e781a9 100644 --- a/docker/ci/test/requirements.txt +++ b/docker/ci/test/requirements.txt @@ -1,7 +1,7 @@ pycocotools opencv-python==4.2.0.34 sphinx -sphinx-material recommonmark scipy pillow +sphinx_rtd_theme \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 1653f40d3d9..ff9b8778b7c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -74,7 +74,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_material" +html_theme = "sphinx_rtd_theme" # Material theme options (see theme.conf for more information) html_theme_options = { diff --git a/oneflow/python/ops/layers.py b/oneflow/python/ops/layers.py index fc985296fa6..120d5277aeb 100644 --- a/oneflow/python/ops/layers.py +++ b/oneflow/python/ops/layers.py @@ -49,8 +49,8 @@ def dense( activation (Optional[remote_blob_util.BlobDef], optional): Activation function. Defaults to None. use_bias (bool, optional): A boolean specifies whether to use a bias vector. Defaults to True. kernel_initializer (Optional[op_conf_util.InitializerConf], optional): Initializer for the kernel weights matrix. Defaults to None. - bias_initializer (Optional[op_conf_util.InitializerConf], optional): [description]. Defaults to None. - kernel_regularizer (Optional[op_conf_util.RegularizerConf], optional): [description]. Defaults to None. + bias_initializer (Optional[op_conf_util.InitializerConf], optional): Initializer for the bias vector. Defaults to None. + kernel_regularizer (Optional[op_conf_util.RegularizerConf], optional): Regularizer function applied to the kernel weights matrix. Defaults to None. bias_regularizer (Optional[op_conf_util.RegularizerConf], optional): Regularizer for the bias vector. Defaults to None. trainable (bool, optional): A boolean specifies whether to train the variables. Defaults to True. name (Optional[str], optional): This layer's name. Defaults to None. @@ -646,7 +646,7 @@ def layer_norm( begin_norm_axis (int, optional): An integer specifies which axis to normalize at first. Defaults to 1. begin_params_axis (int, optional): An integer specifies which axis params at . Defaults to -1. epsilon (float, optional): A small float is added to avoid division by zero. Defaults to 1e-5. - name (Optional[str], optional): This layer's name. Defaults to None. + name (Optional[str], optional): This layer's name. Defaults to None. Returns: remote_blob_util.BlobDef: A normalized `Blob` with same shape of input. @@ -1004,10 +1004,10 @@ def upsample( Args: x ([type]): Input `Blob`. - size (tuple, optional): (height_scale,width_scale) Defaults to (2, 2). + size (tuple, optional): (height_scale, width_scale) Defaults to (2, 2). data_format (str, optional): A string specifies the format of the input `Blob`, one of "NCHW" or "NHWC" (default: "NCHW"). "NCHW" cooresponds to channels_first, i.e. the input `Blob` with shape (batch_size, channels, height, width). "NHWC" cooresponds to channels_last, i.e. the input `Blob` with shape (batch_size, height, width, channels).. Defaults to "NCHW". - interpolation (str, optional): Image interpolation algorithm to enlarge the image size. Defaults to "nearest". + interpolation (str, optional): Image interpolation algorithm to enlarge the image size. Defaults to "nearest". "nearest" and "bilinear" are available now. name ([type], optional): This layer's name. Defaults to None. Raises: @@ -1015,7 +1015,7 @@ def upsample( ValueError: data_format must be "NHWC" or "NCHW" Returns: - [type]: remote_blob_util.BlobDef: A `Blob` with new shape of input. if input size is(2,2),then the new shape is [N, C, 2H, 2W]. + [type]: remote_blob_util.BlobDef: A `Blob` which is the upsampled `x`. If `size` is (2, 2), the shape of return value is [N, C, 2H, 2W]. """ if isinstance(size, int): height_scale = size diff --git a/oneflow/python/ops/math_ops.py b/oneflow/python/ops/math_ops.py index 3cb921c810c..3e98c26651f 100644 --- a/oneflow/python/ops/math_ops.py +++ b/oneflow/python/ops/math_ops.py @@ -36,15 +36,41 @@ def add( y: Union[int, float, remote_blob_util.BlobDef], name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes 'x' add 'y' + """Compute :math:`X + Y` element-wise, math.add supports broadcasting. Analogous to `tf.math.add `_ + + The equation is: + + .. math:: + out = X + Y Args: - x (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - y (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - name (Optional[str], optional): This operator's name. Defaults to None. + x (Union[int, float, remote_blob_util.BlobDef]): A Blob. + y (Union[int, float, remote_blob_util.BlobDef]): A Blob has the same type of x. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the same type as 'x' and 'y' + remote_blob_util.BlobDef: A Blob is added by x and y, and has the same type of x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def addJob(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.add(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([1, 1, 1]).astype(np.float32) + out = addJob(x, y) + + # output [2., 3., 4.] + """ if isinstance(x, (int, float)): return scalar_add(y, x, name) @@ -88,14 +114,36 @@ def _recursive_build_add_n(inputs, name=None): def add_n( inputs: Sequence[remote_blob_util.BlobDef], name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Add all input blobs element-wise. + """Add all the input tensors in element-wise, Analogous to `tf.math.add_n `_ Args: - inputs (Sequence[remote_blob_util.BlobDef]): Sequence of 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + inputs (Sequence[remote_blob_util.BlobDef]): A list of Blob, each Blob has the same shape and type. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the same type as 'inputs' Blobs + remote_blob_util.BlobDef: The sum of the inputs, has the same shape and type as the elements of inputs. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def add_n_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.add_n([x, y]) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([1, 1, 1]).astype(np.float32) + out = add_n_Job(x, y) + print(out) + + # output [2., 3., 4.] + """ return _recursive_build_add_n(inputs, name) @@ -106,15 +154,41 @@ def subtract( y: Union[int, float, remote_blob_util.BlobDef], name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes 'x' subtract 'y' + """Compute x - y element-wise, Analogous to `tf.math.subtract `_ + + The equation is: + + .. math:: + out = X - Y Args: - x (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - y (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - name (Optional[str], optional): This operator's name. Defaults to None. + x (Union[int, float, remote_blob_util.BlobDef]): A Blob. + y (Union[int, float, remote_blob_util.BlobDef]): A Blob has the same type of x. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the same type as 'x' and 'y' + remote_blob_util.BlobDef: A Blob after subtracting, has the same type as x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def subtractJob(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.subtract(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([2, 4, 1]).astype(np.float32) + out = subtractJob(x, y) + + # output [-1., -2., 2.] + """ if isinstance(x, (int, float)): return scalar_add(-1 * y, x, name) @@ -137,15 +211,40 @@ def multiply( y: Union[int, float, remote_blob_util.BlobDef], name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes 'x' multiply 'y' + r"""Compute :math:`x \times y` element-wise, Analogous to `tf.math.multiply `_ + + The equation is: + + .. math:: + out = X \times Y Args: - x (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - y (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - name (Optional[str], optional): This operator's name. Defaults to None. + x (Union[int, float, remote_blob_util.BlobDef]): A Blob. + y (Union[int, float, remote_blob_util.BlobDef]): A Blob has the same type of x. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the same type as 'x' and 'y' + remote_blob_util.BlobDef: A Blob after multiplying, has the same type as x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def multiplyJob(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.multiply(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([2, 3, 3]).astype(np.float32) + out = multiplyJob(x, y) + + # output [2., 6., 9.] """ if isinstance(x, (int, float)): return scalar_mul(y, x, name) @@ -167,15 +266,40 @@ def divide( y: Union[int, float, remote_blob_util.BlobDef], name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes 'x' divide 'y' + r"""Computes the division of x by y, Analogous to `tf.math.divide `_ + + The equation is: + + .. math:: + out = \frac{X}{Y} Args: - x (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - y (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - name (Optional[str], optional): This operator's name. Defaults to None. + x (Union[int, float, remote_blob_util.BlobDef]): A Blob. + y (Union[int, float, remote_blob_util.BlobDef]): A Blob. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the same type as 'x' and 'y' + remote_blob_util.BlobDef: A Blob with same shape as input x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def divideJob(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.divide(x, y) + + x = np.array([25, 16, 9]).astype(np.float32) + y = np.array([10, 4, 2]).astype(np.float32) + out = divideJob(x, y) + + # output [2.5, 4., 4.5] """ if isinstance(x, (int, float)): return scalar_mul(math_unary_elementwise_ops.reciprocal_no_nan(y), x, name) @@ -202,19 +326,44 @@ def floor_mod( y: Union[int, float, remote_blob_util.BlobDef], name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes 'x' mod 'y' + r"""Mod two Blobs, Analogous to `tf.math.floormod `_ + + The equation is: + + .. math:: + out = X \bmod Y Args: - x (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - y (Union[int, float, remote_blob_util.BlobDef]): A 'Blob' with type of 'int' or 'float' - name (Optional[str], optional): This operator's name. Defaults to None. + x (Union[int, float, remote_blob_util.BlobDef]): A Blob + y (Union[int, float, remote_blob_util.BlobDef]): A Blob has the same type of x + name (Optional[str], optional): The name for the operation. Defaults to None. Raises: - NotImplementedError: If 'x' is 'int' or 'float' - NotImplementedError: If 'y' is 'int' or 'float' + NotImplementedError: x must be an int or a float + NotImplementedError: y must be an int or a float Returns: - remote_blob_util.BlobDef: A 'Blob' with the same type as 'x' and 'y' + remote_blob_util.BlobDef: A Blob with same type as input x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def modJob(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.mod(x, y) + + x = np.array([16, 9, 5]).astype(np.float32) + y = np.array([6, 4, 3]).astype(np.float32) + out = modJob(x, y) + + # output [4., 1., 2.] """ if isinstance(x, (int, float)): raise NotImplementedError @@ -377,12 +526,37 @@ def broadcast_floor_mod(x, y, name=None): def tanh( x: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Computes hyperbolic tangent of `x` element-wise. + r"""Computes hyperbolic tangent of `x` element-wise, Analogous to `tf.math.tanh `_ + + The equation is: + + .. math:: + out = \frac{e^x - e^{-x}}{e^x + e^{-x}} Args: - x: Input `Blob`. + x (remote_blob_util.BlobDef): Input Blob + name (Optional[str], optional): The name for the operation. Defaults to None. + Returns: - A `Blob` + remote_blob_util.BlobDef: A Blob. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def tanhJob(x: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.tanh(x) + + x = np.array([-0.5, 0, 0.5]).astype(np.float32) + out = tanhJob(x) + + # output [-0.46211714, 0., 0.46211714] """ return ( @@ -400,12 +574,37 @@ def tanh( def gelu( x: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Gaussian Error Linear Units. + r"""Gelu activation operator, Analogous to `tf.nn.gelu `_ + + The equation is: + + .. math:: + out = 0.5 * x * (1 + tanh(\sqrt{\frac{2}{\pi}} * (x + 0.044715x^{3}))) Args: - x: Input `Blob`. + x (remote_blob_util.BlobDef): Input Blob + name (Optional[str], optional): The name for the operation. Defaults to None. + Returns: - A `Blob` + remote_blob_util.BlobDef: A Blob. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def geluJob(x: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.gelu(x) + + x = np.array([-0.5, 0, 0.5]).astype(np.float32) + out = geluJob(x) + + # output [-0.15426877, 0., 0.34573123] """ return ( flow.user_op_builder(name if name is not None else id_util.UniqueStr("Gelu_")) @@ -422,12 +621,37 @@ def gelu( def relu( x: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""ReLU activation + r"""Relu activation + + The equation is: + + .. math:: + out = max(X, 0) Args: - x: Input `Blob`. + x (remote_blob_util.BlobDef): Input Blob + name (Optional[str], optional): The name for the operation. Defaults to None. + Returns: - A `Blob` + remote_blob_util.BlobDef: An activated Blob. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def reluJob(x: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.relu(x) + + x = np.array([-1, 0, 5]).astype(np.float32) + out = reluJob(x) + + # output [0., 0., 5.] """ return ( @@ -445,12 +669,38 @@ def relu( def sigmoid( x: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Computes sigmoid of `x` element-wise. + r"""Sigmoid activation + + The equation is: + + .. math:: + out = \frac{1}{1 + e^{-x}} Args: - x: Input `Blob`. + x (remote_blob_util.BlobDef): Input Blob + name (Optional[str], optional): The name for the operation. Defaults to None. + Returns: - A `Blob` + remote_blob_util.BlobDef: An activated Blob. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def sigmoidJob(x: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.sigmoid(x) + + x = np.array([-1, 0, 1]).astype(np.float32) + out = sigmoidJob(x) + + # output [0.26894143, 0.5, 0.7310586] + """ return ( flow.user_op_builder( @@ -473,17 +723,63 @@ def unsorted_segment_sum( axis: int = 0, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes the sum along segment of 'data' + r"""Computes the sum along segments of a Blob, Analogous to `tf.math.unsorted_segment_sum `_ Args: - data (remote_blob_util.BlobDef): Input 'Blob' - segment_ids (remote_blob_util.BlobDef): A 'Blob' contains of segment ids - num_segments (int): The number of segments - axis (int, optional): The axis need to be sum. Defaults to 0. - name (Optional[str], optional): This operator's name. Defaults to None. + data (remote_blob_util.BlobDef): Input Blob + segment_ids (remote_blob_util.BlobDef): A Blob should be the size of the first dimension, with consecutive IDs in the range 0 to k (k < d0). + num_segments (int): num_segments should equal the number of distinct segment IDs. + axis (int, optional): The axis of data. Defaults to 0. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A `Blob` with the same type as `data`. + remote_blob_util.BlobDef: A Blob with the same type of data. + + For example: + + .. code-block:: python + + # Example 1: + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def unsorted_segment_sumJob(data: tp.Numpy.Placeholder((3, 4)), + segment_ids: tp.Numpy.Placeholder((4, ), dtype=flow.int32) + )->tp.Numpy: + return flow.math.unsorted_segment_sum(data, segment_ids, num_segments=2, axis=1) + + input_blob = np.array([[1, 2, 3, 4], + [5, 6, 7 ,8], + [9, 10, 11, 12]]).astype(np.float32) + segment_ids = np.array([0, 1, 0, 1]).astype(np.int32) + out = unsorted_segment_sumJob(input_blob, segment_ids) + + # output [[ 4. 6.] + # [12. 14.] + # [20. 22.]] + + # Example 2 + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def unsorted_segment_sumJob(data: tp.Numpy.Placeholder((3, 4)), + segment_ids: tp.Numpy.Placeholder((3, ), dtype=flow.int32) + )->tp.Numpy: + return flow.math.unsorted_segment_sum(data, segment_ids, num_segments=2, axis=0) + + input_blob = np.array([[1, 2, 3, 4], + [5, 6, 7 ,8], + [9, 10, 11, 12]]).astype(np.float32) + segment_ids = np.array([0, 1, 0]).astype(np.int32) + out = unsorted_segment_sumJob(input_blob, segment_ids) + + # output [[10. 12. 14. 16.] + # [ 5. 6. 7. 8.]] + """ return ( flow.user_op_builder( @@ -509,17 +805,44 @@ def unsorted_segment_sum_like( axis: int = 0, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computes the sum along segment of 'data' + r"""Computes the sum along segments of a Blob, the output shape is the same as the `like` Blob. Args: - data (remote_blob_util.BlobDef): Input 'Blob' - segment_ids (remote_blob_util.BlobDef): A 'Blob' contains of segment ids - like (remote_blob_util.BlobDef): The shape for output - axis (int, optional): The axis need to be sum. Defaults to 0. - name (Optional[str], optional): This operator's name. Defaults to None. + data (remote_blob_util.BlobDef): Input Blob + segment_ids (remote_blob_util.BlobDef): A Blob should be the size of the first dimension, with consecutive IDs in the range 0 to k (k < d0). + like (remote_blob_util.BlobDef): The input Blob which specifies shape + axis (int, optional): The axis of data. Defaults to 0. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A `Blob` with the same shape as `like`. + remote_blob_util.BlobDef: A Blob. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def unsorted_segment_sum_like_Job(data: tp.Numpy.Placeholder((3, 4)), + segment_ids: tp.Numpy.Placeholder((3, ), dtype=flow.int32), + like: tp.Numpy.Placeholder((2, 4), dtype=flow.float32) + )->tp.Numpy: + return flow.math.unsorted_segment_sum_like(data, segment_ids, like, axis=0) + + input_blob = np.array([[1, 2, 3, 4], + [5, 6, 7 ,8], + [9, 10, 11, 12]]).astype(np.float32) + segment_ids = np.array([0, 1, 0]).astype(np.int32) + like = np.zeros(shape=(2, 4), dtype=np.float32) + + out = unsorted_segment_sum_like_Job(input_blob, segment_ids, like) + + # output [[10. 12. 14. 16.] + # [ 5. 6. 7. 8.]] + """ return ( flow.user_op_builder( @@ -544,16 +867,50 @@ def unsorted_batch_segment_sum( num_segments: int, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Convert sparse Blob 'data' into a dense 'Blob' according to sement_ids + r"""It is similar with `unsorted_segment_sum`, the difference is that `unsorted_batch_segment_sum` brings a `batch axis`. We can do the segment sum in different batch of data. + + For example, the segment id is like: + + .. code-block:: python + + [[0 0 0 1 2 2 3 3], + [0 0 1 1 2 3 3 3]] Args: - data (remote_blob_util.BlobDef): Input 'Blob' - segment_ids (remote_blob_util.BlobDef): A 'Blob' contains of segment ids - num_segments (int): The number of segments - name (Optional[str], optional): This operator's name. Defaults to None. + data (remote_blob_util.BlobDef): Input Blob + segment_ids (remote_blob_util.BlobDef): A Blob with shape (d0, d1). The d0, d1 are the first and second dimension of data. + num_segments (int): num_segments should equal the number of distinct segment IDs. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A dense 'Blob' + remote_blob_util.BlobDef: A Blob. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def unsorted_batch_segment_sum_Job(data: tp.Numpy.Placeholder((3, 4)), + segment_ids: tp.Numpy.Placeholder((3, 4), dtype=flow.int32) + )->tp.Numpy: + return flow.math.unsorted_batch_segment_sum(data, segment_ids, 2) + + input_blob = np.array([[1, 2, 3, 4], + [1, 2, 3 ,4], + [1, 2, 3, 4]]).astype(np.float32) + segment_ids = np.array([[0, 0, 0, 1], + [0, 0, 1, 0], + [0, 1, 0, 0]]).astype(np.int32) + out = unsorted_batch_segment_sum_Job(input_blob, segment_ids) + + # output [[6. 4.] + # [7. 3.] + # [8. 2.]] + """ return ( flow.user_op_builder( @@ -574,15 +931,34 @@ def unsorted_batch_segment_sum( def cast( x: remote_blob_util.BlobDef, dtype: dtype_util.dtype, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a `Blob` of given data type `dtype` and indentical shape to `x` + r"""The op takes input x and casts it to the output with `dtype` Args: - x (remote_blob_util.BlobDef): Input `Blob`. - dtype (int): A OneFlow data type. For instance, `oneflow.float`. - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): Input Blob + dtype (dtype_util.dtype): Data type of the output + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A `Blob` + remote_blob_util.BlobDef: A Blob + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def cast_Job(x: tp.Numpy.Placeholder((3, ), dtype=flow.float32) + )->tp.Numpy: + return flow.cast(x, dtype=flow.int32) + + x = np.array([1, 2, 3]).astype(np.float32) + out = cast_Job(x) + + # out.dtype = "int32" + """ if x.dtype == dtype: return x @@ -605,15 +981,35 @@ def cast( def equal( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x == y) element-wise + r"""Returns the truth value of :math:`{x}=={y}` element-wise. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def equal_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.equal(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([1, 2, 1]).astype(np.float32) + out = equal_Job(x, y) + + # output [1 1 0] """ return build_broadcast_binary_op("broadcast_equal", x, y, name) @@ -622,15 +1018,35 @@ def equal( def not_equal( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x != y) element-wise + r"""Returns the truth value of :math:`{x}!={y}` element-wise. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def not_equal_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.not_equal(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([1, 2, 1]).astype(np.float32) + out = not_equal_Job(x, y) + + # output [0 0 1] """ return build_broadcast_binary_op("broadcast_not_equal", x, y, name) @@ -639,15 +1055,35 @@ def not_equal( def less( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x < y) element-wise + r"""Returns the truth value of :math:`x < y` element-wise. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def less_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.less(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([1, 2, 4]).astype(np.float32) + out = less_Job(x, y) + + # output [0 0 1] """ return build_broadcast_binary_op("broadcast_less", x, y, name) @@ -656,15 +1092,35 @@ def less( def less_equal( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x <= y) element-wise + r"""Returns the truth value of :math:`x <= y` element-wise. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def less_equal_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.less_equal(x, y) + + x = np.array([1, 2, 3]).astype(np.float32) + y = np.array([1, 1, 4]).astype(np.float32) + out = less_equal_Job(x, y) + + # output [1 0 1] """ return build_broadcast_binary_op("broadcast_less_equal", x, y, name) @@ -673,15 +1129,35 @@ def less_equal( def greater( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x > y) element-wise + r"""Returns the truth value of :math:`x > y` element-wise. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def greater_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.greater(x, y) + + x = np.array([1, 1, 4]).astype(np.float32) + y = np.array([1, 2, 3]).astype(np.float32) + out = greater_Job(x, y) + + # output [0 0 1] """ return build_broadcast_binary_op("broadcast_greater", x, y, name) @@ -690,15 +1166,35 @@ def greater( def greater_equal( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x >= y) element-wise + r"""Returns the truth value of :math:`x >= y` element-wise. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def greater_equal_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.greater_equal(x, y) + + x = np.array([1, 1, 4]).astype(np.float32) + y = np.array([1, 2, 3]).astype(np.float32) + out = greater_equal_Job(x, y) + + # output [1 0 1] """ return build_broadcast_binary_op("broadcast_greater_equal", x, y, name) @@ -707,15 +1203,41 @@ def greater_equal( def logical_and( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' of (x && y) element-wise + r"""Logical AND function. + + Each element is calculated by: + + .. math:: + out = X ∧ Y Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with value '1' or '0' + remote_blob_util.BlobDef: A Blob with int8 type. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def logical_and_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.logical_and(x, y) + + x = np.array([1, 0, 1]).astype(np.float32) + y = np.array([0, 0, 1]).astype(np.float32) + out = logical_and_Job(x, y) + + # output [0 0 1] + """ return build_broadcast_binary_op("broadcast_logical_and", x, y, name) @@ -724,15 +1246,36 @@ def logical_and( def broadcast_min( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' with the min value of (x < y ? x : y) element-wise + r"""Returns the min of x and y element-wise, this op supports broadcasting. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob. Must have the same type of x + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with min value + remote_blob_util.BlobDef: A Blob, has the same type of x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def minimum_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.minimum(x, y) + + x = np.array([2, 3, 4]).astype(np.float32) + y = np.array([4, 2, 1]).astype(np.float32) + out = minimum_Job(x, y) + + # output [2. 2. 1.] + """ return build_broadcast_binary_op("broadcast_minimum", x, y, name) @@ -741,15 +1284,35 @@ def broadcast_min( def broadcast_max( x: remote_blob_util.BlobDef, y: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Return a 'Blob' with the min value of (x > y ? x : y) element-wise + """Returns the max of x and y element-wise, this op supports broadcasting. Args: - x (remote_blob_util.BlobDef): a 'Blob' - y (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + x (remote_blob_util.BlobDef): A Blob + y (remote_blob_util.BlobDef): A Blob. Must have the same type of x + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with max value + remote_blob_util.BlobDef: A Blob, has the same type of x. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def maximum_Job(x: tp.Numpy.Placeholder((3, )), + y: tp.Numpy.Placeholder((3, )) + )->tp.Numpy: + return flow.math.maximum(x, y) + + x = np.array([2, 3, 4]).astype(np.float32) + y = np.array([4, 2, 1]).astype(np.float32) + out = maximum_Job(x, y) + + # output [4. 3. 4.] """ return build_broadcast_binary_op("broadcast_maximum", x, y, name) @@ -761,16 +1324,50 @@ def elem_cnt( dtype: Optional[dtype_util.dtype] = None, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Reduce shape emements count accross 'axis' + """Computes the product of input_blob's dimensions along the parameter `axis`. By default, all the dimensions will be computed. Args: - input_blob (remote_blob_util.BlobDef): a 'Blob' - axis (Optional[Sequence[int]], optional): The axis need to be reduced. Defaults to None. - dtype (Optional[int], optional): A OneFlow data type (flow.int32). Defaults to None. - name (Optional[str], optional): This operator's name. Defaults to None. + input_blob (remote_blob_util.BlobDef): Input Blob + axis (Optional[Sequence[int]], optional): The dimensions along which the op is performed. Defaults to None. + dtype (Optional[dtype_util.dtype], optional): The data type. Defaults to None. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' + remote_blob_util.BlobDef: A Blob + + For example: + + .. code-block:: python + + # Example 1: + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def elem_cnt_Job(x: tp.Numpy.Placeholder((3, 4, 5)) + )->tp.Numpy: + return flow.math.reduced_shape_elem_cnt(x, axis=[0, 1]) + + x = np.ones(shape=(3, 4, 5), dtype=np.float32) + out = elem_cnt_Job(x) # 3 x 4 = 12 + + # output [12] + + # Example 2: + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def elem_cnt_Job(x: tp.Numpy.Placeholder((3, 4, 5)) + )->tp.Numpy: + return flow.math.reduced_shape_elem_cnt(x) + + x = np.ones(shape=(3, 4, 5), dtype=np.float32) + out = elem_cnt_Job(x) # 3 x 4 x 5 = 60 + + # output [60] """ op_conf = op_conf_util.OperatorConf() setattr( @@ -801,16 +1398,34 @@ def top_k( sorted: bool = True, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Returns a 'Blob' whose value is the index of top-k values accross the last axes of 'input' + """Finds the indices of the k largest entries for the last dimension, the difference between other framework is that oneflow only return the indices. Args: - input (remote_blob_util.BlobDef): a 'Blob' + input (remote_blob_util.BlobDef): The input Blob k (int, optional): Number of top elements to look for along the last dimension. Defaults to 1. - sorted (bool, optional): 'True' or 'False'. Defaults to True. - name (Optional[str], optional): This operator's name. Defaults to None. + sorted (bool, optional): If true the resulting k elements will be sorted by the values in descending order. Defaults to True. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the index 'input' + remote_blob_util.BlobDef: A Blob(dtype=int32) contains the indices of the k largest elements. + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def topk_Job(x: tp.Numpy.Placeholder((5, )) + )->tp.Numpy: + return flow.math.top_k(x, 2) + + x = np.array([1, 3, 8, 7, 2], dtype=np.float32) + out = topk_Job(x) + + # output [2 3] """ return ( flow.user_op_builder(name if name is not None else id_util.UniqueStr("TopK_")) @@ -829,14 +1444,34 @@ def top_k( def argmax( input: remote_blob_util.BlobDef, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Returns a 'Blob' whose value is the index with largest value accross the last axes of 'input' + """The op computes the index with the largest value of a Blob. Args: - input (remote_blob_util.BlobDef): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. + input (remote_blob_util.BlobDef): Input Blob + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with type 'flow.int32' + remote_blob_util.BlobDef: A Blob(dtype=int32) contains the index with the largest value of `input` + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def argmax_Job(x: tp.Numpy.Placeholder((2, 5)) + )->tp.Numpy: + return flow.math.argmax(x) + + x = np.array([[1, 3, 8, 7, 2], + [1, 9, 4, 3, 2]], dtype=np.float32) + + out = argmax_Job(x) + + # output [2 1] """ return ( flow.user_op_builder(name if name is not None else id_util.UniqueStr("ArgMax_")) @@ -864,6 +1499,28 @@ def broadcast_to_compatible_with( Returns: remote_blob_util.BlobDef: A 'Blob' with the biggest shape + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def broadcast_to_compatible_with_Job(x: tp.Numpy.Placeholder((4, 1, 1)) + )->tp.Numpy: + blob_a = flow.constant(value=1, dtype=flow.float32, shape=(1, 2, 1)) + blob_b = flow.constant(value=1, dtype=flow.float32, shape=(1, 1, 3)) + + return flow.math.broadcast_to_compatible_with(x, [blob_a, blob_b]) + + x = np.ones(shape=(4, 1, 1), dtype=np.float32) + + out = broadcast_to_compatible_with_Job(x) + + # output.shape (4, 2, 3) """ assert isinstance(compatible, (list, tuple)) if name is None: @@ -893,19 +1550,43 @@ def clip_by_value( max_value: Optional[Union[int, float]] = None, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Clip the 'values' in the range + """This op clips Blob values to a specified min value and max value. + + The equation is: + + .. math:: + out = MIN(MAX(x, min), max) Args: - values (remote_blob_util.BlobDef): a 'Blob' - min_value (Optional[Union[int, float]], optional): The min value 'int' or 'float'. Defaults to None. - max_value (Optional[Union[int, float]], optional): The max value 'int' or 'float'. Defaults to None. - name (Optional[str], optional): This operator's name. Defaults to None. + values (remote_blob_util.BlobDef): Input Blob + min_value (Optional[Union[int, float]], optional): The minimum value to clip by. Defaults to None. + max_value (Optional[Union[int, float]], optional): The maximum value to clip by. Defaults to None. + name (Optional[str], optional): The name for the operation. Defaults to None. Raises: - ValueError: If both 'min_value' and 'max_value' are None + ValueError: min_value and max_value `cannot be None at the same time` Returns: - remote_blob_util.BlobDef: A 'Blob' with value in the range of [min_value, max_value] or [min_value, 'values'.max_value] or ['values'.min_value, max_value] + remote_blob_util.BlobDef: A clipped Blob + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def clip_by_value_Job(x: tp.Numpy.Placeholder((4, )) + )->tp.Numpy: + return flow.math.clip_by_value(x, min_value=-1, max_value=5) + + x = np.array([-2, 1, 4, 7], dtype=np.float32) + + out = clip_by_value_Job(x) + + # output [-1. 1. 4. 5.] """ if name is None: name = id_util.UniqueStr("ClipByValue_") @@ -952,16 +1633,41 @@ def l2_normalize( epsilon: float = 1e-12, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""L2 Normalization + r"""Use L2 norm to normalizes along dimension `axis` + + The equation is: + + .. math:: + out = \frac{x}{\sqrt{\Sigma{x^2}+\epsilon}} Args: - input (remote_blob_util.BlobDef): a 'Blob' - axis (Optional[int], optional): Dimension along which to normalize. Defaults to None. - epsilon (float, optional): a lower bound value for the norm. Defaults to 1e-12. - name (Optional[str], optional): This operator's name. Defaults to None. + input (remote_blob_util.BlobDef): Input Blob + axis (Optional[int], optional): The axis on which to apply L2 normalization. Defaults to None. + epsilon (float, optional): The epsilon value is used to avoid division by zero. Defaults to 1e-12. + name (Optional[str], optional): The name for the operation. Defaults to None. Returns: - remote_blob_util.BlobDef: A 'Blob' with the same shape as 'input' + remote_blob_util.BlobDef: The normalized Blob + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def l2_normalize_Job(x: tp.Numpy.Placeholder((4, )) + )->tp.Numpy: + return flow.math.l2_normalize(x, axis=0) + + x = np.array([1, 2, 3, 4], dtype=np.float32) + + out = l2_normalize_Job(x) + + # output [0.18257418 0.36514837 0.5477226 0.73029673] + """ if axis < 0: axis += len(input.shape) @@ -989,15 +1695,36 @@ def squared_difference( y: Union[int, float, remote_blob_util.BlobDef], name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Returns (x-y)(x-y) element-wise + """This op computes :math:`(x - y)^2` element-wise. Args: - x (Union[int, float, remote_blob_util.BlobDef]): a 'Blob' - y (Union[int, float, remote_blob_util.BlobDef]): a 'Blob' - name (Optional[str], optional): This operator's name. Defaults to None. - + x (Union[int, float, remote_blob_util.BlobDef]): A Blob + y (Union[int, float, remote_blob_util.BlobDef]): A Blob with the same type of x + name (Optional[str], optional): The name for the operation. Defaults to None. + Returns: - remote_blob_util.BlobDef: A 'Blob' with type of 'int' or 'float' + remote_blob_util.BlobDef: A Blob + + For example: + + .. code-block:: python + + import oneflow as flow + import numpy as np + import oneflow.typing as tp + + @flow.global_function() + def squared_difference_Job(x: tp.Numpy.Placeholder((4, )), + y: tp.Numpy.Placeholder((4, )) + )->tp.Numpy: + return flow.math.squared_difference(x, y) + + x = np.array([1, 2, 3, 4], dtype=np.float32) + y = np.array([2, 4, 6, 8], dtype=np.float32) + + out = squared_difference_Job(x, y) + + # output [ 1. 4. 9. 16.] """ name_subtract, name_square = None, None if name is not None: diff --git a/oneflow/python/ops/nn_ops.py b/oneflow/python/ops/nn_ops.py index 0ee7e2d1641..b8eee8dec63 100644 --- a/oneflow/python/ops/nn_ops.py +++ b/oneflow/python/ops/nn_ops.py @@ -19,7 +19,7 @@ import os import sys import random -from typing import Union, Optional, Sequence, Tuple +from typing import Union, Optional, Sequence, Tuple, List import oneflow as flow import oneflow.core.operator.op_conf_pb2 as op_conf_util import oneflow.core.register.logical_blob_id_pb2 as logical_blob_id_util @@ -207,17 +207,17 @@ def conv1d( Args: input (remote_blob_util.BlobDef): A 3D input `Blob`. [batch_num, channel, width] - filters (remote_blob_util.BlobDef): A `Blob` with the same type as `input` and has the shape [out_channels, in_channels//groups, filter_width] for NCW, or [out_channels, filter_width, in_channels//groups] for NWC` + filters (remote_blob_util.BlobDef): A `Blob` with the same type as `input` and has the shape [out_channels, in_channels//groups, filter_width] for `NCW`, or [out_channels, filter_width, in_channels//groups] for `NWC` strides (Union[int, Tuple[int]]): An int or list of `ints` that has length `1`. The stride of the sliding window for each dimension of `input`. padding (Union[str, Tuple[IntPair, IntPair, IntPair]]): padding: `string` `"SAME"` or `"SAME_LOWER"` or `"SAME_UPPER"` or `"VALID" or Tuple[IntPair, IntPair, IntPair]` indicating the type of padding algorithm to use, or a list indicating the explicit paddings at the start and end of each dimension. data_format (str, optional): `"NWC" or "NCW"`. Defaults to `"NCW"`. - dilations (Optional[Union[int, Tuple[int]]], optional): An int or list of `ints` that has length `1`. The dilation factor for each dimension of`input`. Defaults to None. + dilations (Optional[Union[int, Tuple[int]]], optional): An int or list of `ints` that has length `1`. The dilation factor for each dimension of `input`. Defaults to None. groups (int, optional): int value greater than 0. Defaults to 1. name (Optional[str], optional): This operator's name. Defaults to None. Raises: ValueError: strides must be an int or a list. - ValueError: padding must be "SAME" or `"SAME_LOWER" or "SAME_UPPER" or "VALID" or Tuple[IntPair, IntPair, IntPair, IntPair]. + ValueError: padding must be "SAME" or "SAME_LOWER" or "SAME_UPPER" or "VALID" or Tuple[IntPair, IntPair, IntPair, IntPair]. ValueError: data_format must be "NWC" or "NCW". ValueError: dilations must be an int or a list. ValueError: invalid data_format. @@ -335,7 +335,7 @@ def conv2d( strides (Union[int, IntPair]): An int or list of `ints` that has length `2`. The stride of the sliding window for each dimension of `input`. padding (Union[str, Tuple[IntPair, IntPair, IntPair, IntPair]]): padding: `string` `"SAME"` or `"SAME_LOWER"` or `"SAME_UPPER"` or `"VALID" or Tuple[IntPair, IntPair, IntPair, IntPair]` indicating the type of padding algorithm to use, or a list indicating the explicit paddings at the start and end of each dimension. data_format (str, optional): `"NHWC" or "NCHW"`. Defaults to `"NCHW"`. - dilations (Optional[Union[int, IntPair]], optional): An int or list of `ints` that has length `2`. The dilation factor for each dimension of`input`. Defaults to None. + dilations (Optional[Union[int, IntPair]], optional): An int or list of `ints` that has length `2`. The dilation factor for each dimension of `input`. Defaults to None. groups (int, optional): int value greater than 0. Defaults to 1. name (Optional[str], optional): This operator's name. Defaults to None. @@ -499,7 +499,7 @@ def conv3d( Args: input (remote_blob_util.BlobDef): A 5D input `Blob`. [batch_num, channel, depth, height, width] filters (remote_blob_util.BlobDef): A `Blob` with the same type as `input` and has the shape `[out_channels, in_channels//groups, filter_depth, filter_height, filter_width] for NCDHW, or [out_channels, filter_depth, filter_height, filter_width, in_channels//groups] for NDHWC` - strides (Union[int, Sequence[int]]): An int or list of `ints` that has length `3`. The stride of the sliding window for each dimension of `input`. + strides (Union[int, Sequence[int]]): An `int` or `list of ints` that has length `3`. The stride of the sliding window for each dimension of `input`. padding (Union[str, Tuple[IntPair, IntPair, IntPair, IntPair, IntPair]]): padding: `string` `"SAME"` or `"SAME_LOWER"` or `"SAME_UPPER"` or `"VALID" or Tuple[IntPair, IntPair, IntPair, IntPair, IntPair]` indicating the type of padding algorithm to use, or a list indicating the explicit paddings at the start and end of each dimension. data_format (str, optional): `"NDHWC" or "NCDHW"`. Defaults to `"NCDHW"`. dilations (Optional[Union[int, Sequence[int]]], optional): An int or list of `ints` that has length `3`. The dilation factor for each dimension of `input`. Defaults to None. @@ -508,7 +508,7 @@ def conv3d( Raises: ValueError: strides must be an int or a list. - ValueError: padding must be "SAME" or `"SAME_LOWER" or "SAME_UPPER" or "VALID" or Tuple[IntPair, IntPair, IntPair, IntPair, IntPair]. + ValueError: padding must be "SAME" or "SAME_LOWER" or "SAME_UPPER" or "VALID" or Tuple[IntPair, IntPair, IntPair, IntPair, IntPair]. ValueError: data_format must be "NDHWC" or "NCDHW". ValueError: dilations must be an int or a list. ValueError: invalid data_format. @@ -605,7 +605,24 @@ def conv3d( @oneflow_export("nn.moments") -def moments(x, axes, keepdims=False, name=None): +def moments( + x: remote_blob_util.BlobDef, + axes: List[int], + keepdims: Optional[bool] = False, + name: Optional[str] = None, +) -> remote_blob_util.BlobDef: + """Analogous to `tf.nn.moments `_ + + Args: + x (remote_blob_util.BlobDef): A Blob + axes (List): Array of ints. Axes along which to compute the mean and variance + keepdims (bool, optional): Whether to keep the same dimensanality as the input x. Defaults to False. + name (str, optional): The operator's name. Defaults to None. + + Returns: + remote_blob: Two Blobs, mean and variance. + """ assert isinstance(axes, list) if name is None: name = id_util.UniqueStr("Moments_") @@ -766,8 +783,7 @@ def bias_add( name (Optional[str], optional): This operator's name. Defaults to None. Raises: - ValueError: ValueError if data format is unrecognized, if value has less than two dimensions with '`N..C'`/None data_format or value has less than three dimensions with '`NC..'` data_format, if bias is a vector, - or if the size of bias does not match the size of the channel dimension of value. + ValueError: ValueError if data format is unrecognized, if value has less than two dimensions with '`N..C'`/None data_format or value has less than three dimensions with '`NC..'` data_format, if bias is a vector, or if the size of bias does not match the size of the channel dimension of value. Returns: remote_blob_util.BlobDef: A `Blob` with the same type as value. @@ -887,9 +903,9 @@ def max_pool2d( input (remote_blob_util.BlobDef): A 4-D `Blob` of the format specified by data_format. ksize (Union[int, IntPair]): An int or list of ints that has length 1, 2. The size of the window for each dimension of the input `Blob`. strides (Union[int, IntPair]): An int or list of ints that has length 1, 2. The stride of the sliding window for each dimension of the input `Blob`. - padding (str): '`VALID'` or '`SAME' or '`SAME_LOWER' or '`SAME_UPPER' or Tuple[IntPair, IntPair, IntPair, IntPair]`. The padding algorithm. + padding (str): '`VALID'` or '`SAME'` or '`SAME_LOWER'` or '`SAME_UPPER'` or Tuple[IntPair, IntPair, IntPair, IntPair]`. The padding algorithm. data_format (str, optional): '`NHWC'`, '`NCHW'` or '`NCHW_VECT_C'`. Defaults to "NCHW". - name (Optional[str], optional): This operator's name(optional).. Defaults to None. + name (Optional[str], optional): This operator's name(optional). Defaults to None. Returns: remote_blob_util.BlobDef: A `Blob` of format specified by data_format. The max pooled output `Blob`. @@ -985,7 +1001,7 @@ def max_pool3d( input (remote_blob_util.BlobDef): A 5-D `Blob` of the format specified by data_format. ksize (Union[int, Sequence[int]]): An int or list of ints that has length 1, 3 or 5. The size of the window for each dimension of the input `Blob`. strides (Union[int, Sequence[int]]): An int or list of ints that has length 1, 3 or 5. The stride of the sliding window for each dimension of the input `Blob`. - padding (str): '`VALID'` or '`SAME'` or '`SAME_LOWER'` or '`SAME_UPPER or Sequence[Sequence[int]]'`. + padding (str): '`VALID'` or '`SAME'` or '`SAME_LOWER'` or '`SAME_UPPER'` or '`Sequence[Sequence[int]]'`. data_format (str, optional): "NDHWC" or "NCDHW". Defaults to "NCDHW". name (Optional[str], optional): This operator's name(optional). @@ -1093,10 +1109,15 @@ def softmax( ) -> remote_blob_util.BlobDef: r"""Computes softmax activations. Analogous to `tf.nn.softmax `_ + For each element, we apply: + + .. math:: + S_i = \frac{e^i}{\sum_1^j e^j } + Args: logits (remote_blob_util.BlobDef): A non-empty `Blob`. - axis (Optional[int], optional): .The dimension softmax would be performed on. Defaults to None. - name (Optional[str], optional): . This operator's name(optional). Defaults to None. + axis (Optional[int], optional): The dimension softmax would be performed on. Defaults to None. + name (Optional[str], optional): This operator's name(optional). Defaults to None. Returns: remote_blob_util.BlobDef: A `Blob` has the same type and shape as logits. @@ -1178,7 +1199,7 @@ def sparse_cross_entropy( prediction: remote_blob_util.BlobDef, name: Optional[str] = None, ) -> remote_blob_util.BlobDef: - r"""Computer sparse cross entropy + r"""Computes sparse cross entropy Args: labels (remote_blob_util.BlobDef): A `Blob` of shape [d_0, d_1, ..., d_{r-1}] (where r is rank of labels and result). Each entry in labels must be an index in [0, num_classes). @@ -1405,7 +1426,7 @@ def random_mask_like( name (Optional[str], optional): This operator's name(optional). Defaults to None. Returns: - remote_blob_util.BlobDef: A random mask `Blob` of the same shape of '`like'`. + remote_blob_util.BlobDef: A random mask `Blob` of the same shape of `like`. Raises: ValueError: If rate is not in [0, 1). Rate=1 is not allowed. @@ -1800,7 +1821,10 @@ def deconv2d_torch( def leaky_relu( x: remote_blob_util.BlobDef, alpha: float = 0.2, name: Optional[str] = None ) -> remote_blob_util.BlobDef: - r"""Leaky ReLU activation value + r"""Leaky ReLU activation value, Analogous to `tf.nn.leaky_relu `_ + + .. math:: + out = max(x, alpha*x) Args: x (remote_blob_util.BlobDef): A `Blob` representing preactivation values. @@ -1808,7 +1832,7 @@ def leaky_relu( name (Optional[str], optional): This operator's name(optional). Defaults to None. Returns: - remote_blob_util.BlobDef: The activation `Blob` + remote_blob_util.BlobDef: The activation `Blob`. """ return ( flow.user_op_builder(