Skip to content

Commit

Permalink
按在线文档需求 61~70 更新了部分文档 (PaddlePaddle#49014)
Browse files Browse the repository at this point in the history 
* Update docstring:
1. 去除 python/paddle/tensor/manipulation.py 中 cast 函数描述中的 This OP；
2. 调整 python/paddle/fluid/layers/control_flow.py 中 Print 函数中参数描述的顺序，添加 optional 描述；
3. 为 python/paddle/tensor/logic.py 中 logical_and 函数添加 optional 描述；
4. 为 python/paddle/fluid/reader.py 中 DataLoader 类中 from_generator、from_dataset 函数添加 optional 描述；
5. 在 python/paddle/fluid/layers/nn.py 中 crf_decoding 函数的 param_attr 在使用中确实可视为存在默认值 None，故添加 optional 描述；
6. 修复 python/paddle/static/nn/common.py 中 data_norm 函数描述里 tex 语法错误的问题，并一并修复同一文件中的相同问题。

* 根据 review 意见修改部分内容。

* 将谓语动词去掉第三人称单数形式。

* 同步中文文档变更。

* string-->str; test=document_fix

Co-authored-by: Ligoml <39876205+Ligoml@users.noreply.github.com>
  • Loading branch information
@LearningPawn @Ligoml
LearningPawn and Ligoml authored Dec 15, 2022
1 parent 88898fd commit dd900b3
Show file tree
Hide file tree
Showing 6 changed files with 81 additions and 80 deletions.
18 changes: 9 additions & 9 deletions python/paddle/fluid/layers/control_flow.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -294,27 +294,27 @@ def Print(
tensor `t`.
Args:
input (Variable): A Tensor to print.
summarize (int): Number of elements in the tensor to be print. If it's
value is -1, then all elements in the tensor will be print.
message (str): A string message to print as a prefix.
first_n (int): Only log `first_n` number of times.
input (Tensor): A Tensor to print.
first_n (int, optional): Only log `first_n` number of times. Default: -1.
message (str, optional): A string message to print as a prefix. Default: None.
summarize (int, optional): Number of elements in the tensor to be print. If
it's value is -1, then all elements in the tensor will be print.
print_tensor_name (bool, optional): Print the tensor name. Default: True.
print_tensor_type (bool, optional): Print the tensor type. Defaultt: True.
print_tensor_shape (bool, optional): Print the tensor shape. Default: True.
print_tensor_layout (bool, optional): Print the tensor layout. Default: True.
print_tensor_lod (bool, optional): Print the tensor lod. Default: True.
print_phase (str): Which phase to displace, including 'forward',
print_phase (str, optional): Which phase to displace, including 'forward',
'backward' and 'both'. Default: 'both'. If set to 'backward', will
only print the gradients of input tensor; If set to 'both', will
both print the input tensor itself and the gradients of input tensor.
Returns:
Variable: Output tensor.
Tensor: Output tensor.
NOTES:
The input and output are two different variables, and in the
following process, you should use the output variable but not the input,
The input and output are two different Tensor, and in the
following process, you should use the output Tensor but not the input,
otherwise, the print layer doesn't have backward.
Examples:
Expand Down
4 changes: 2 additions & 2 deletions python/paddle/fluid/layers/sequence_lod.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1056,7 +1056,7 @@ def sequence_unpad(x, length, name=None):
"""
Note:
The input of the OP is Tensor and the output is LoDTensor. For padding operation, See:** :ref:`api_fluid_layers_sequence_pad`
The input of this API is Tensor and the output is LoDTensor. For padding operation, See:** :ref:`api_fluid_layers_sequence_pad`
Remove the padding data from the input based on the length information and returns a LoDTensor.
Expand Down Expand Up @@ -1084,7 +1084,7 @@ def sequence_unpad(x, length, name=None):
Supported data types: float32, float64, int32, int64.
length(Variable): A 1D Tensor that stores the actual length of each sample, and the Tensor
has the same shape with the 0th dimension of the X . Supported data types: int64.
name(str|None): The default value is None. Normally there is no need for user to set this property.
name(str|None, optional): The default value is None. Normally there is no need for user to set this property.
For more information, please refer to :ref:`api_guide_Name`
Returns:
Expand Down
24 changes: 12 additions & 12 deletions python/paddle/fluid/reader.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -660,28 +660,28 @@ def from_generator(
capacity (int): capacity of the queue maintained in DataLoader.
The unit is batch number. Set larger capacity if your reader
is fast.
use_double_buffer (bool): whether to use double_buffer_reader.
use_double_buffer (bool, optional): whether to use double_buffer_reader.
If use_double_buffer=True, the DataLoader would prefetch next
batch data asynchronously, so it would speed up data feeding
and occupies a little more CPU or GPU memory, i.e., the memory
of one batch input data.
iterable (bool): whether the created DataLoader is iterable.
return_list (bool): whether the return value on each device is
iterable (bool, optional): whether the created DataLoader is iterable.
return_list (bool, optional): whether the return value on each device is
presented as a list. It is only valid when iterable=True.
If return_list=False, the return value on each device would
be a dict of str -> LoDTensor, where the key of the dict is
the name of each fed Tensors. If return_list=True, the
return value on each device would be a list(LoDTensor). It is
recommended to use return_list=False in static graph mode and
use return_list=True in dygraph mode.
use_multiprocess (bool): whether to use multi-process to speed up
the data loading process in dygraph. Note: this parameter only
can be used in the dygraph mode. In the static graph mode,
use_multiprocess (bool, optional): whether to use multi-process to
speed up the data loading process in dygraph. Note: this parameter
only can be used in the dygraph mode. In the static graph mode,
whether this parameter is set or not has no effect.
The Default value is False.
drop_last (bool): whether to drop the last batches whose number is
less than the CPU core/GPU card number. The default value is
True. In training phase, users should not set drop_last=False,
drop_last (bool, optional): whether to drop the last batches whose
number is less than the CPU core/GPU card number. The default
value is True. In training phase, users should not set drop_last=False,
because all CPU cores/GPU cards must read data from DataLoader.
In inference phase, users can set drop_last=False, so that the
last batches whose number is less than the CPU core/GPU card
Expand Down Expand Up @@ -974,9 +974,9 @@ def from_dataset(dataset, places, drop_last=True):
places (list(CUDAPlace)|list(CPUPlace)|list(str)): places where the result
data should be converted. If places is list of string, the string in the list
can be ``cpu``, ``gpu:x`` and ``gpu_pinned``, where x is the index of the GPUs.
drop_last (bool): whether to drop the last batch whose sample
number is less than batch size. If drop_last = True, they
would be dropped. If drop_last = False, they would be kept.
drop_last (bool, optional): whether to drop the last batch whose
sample number is less than batch size. If drop_last = True,
they would be dropped. If drop_last = False, they would be kept.
Returns:
loader (DataLoader): the created DataLoader object, which can be
Expand Down
109 changes: 55 additions & 54 deletions python/paddle/static/nn/common.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -203,13 +203,13 @@ def instance_norm(
.. math::
\\mu_{\\beta} &\\gets \\frac{1}{HW} \\sum_{i=1}^{HW} x_i \\qquad &//\\
\\ mean\ of\ one\ feature\ map\ in\ mini-batch \\\\
\\sigma_{\\beta}^{2} &\\gets \\frac{1}{HW} \\sum_{i=1}^{HW}(x_i - \\
\\mu_{\\beta})^2 \\qquad &//\ variance\ of\ one\ feature\ map\ in\ mini-batch \\\\
\\hat{x_i} &\\gets \\frac{x_i - \\mu_\\beta} {\\sqrt{\\
\\sigma_{\\beta}^{2} + \\epsilon}} \\qquad &//\ normalize \\\\
y_i &\\gets \\gamma \\hat{x_i} + \\beta \\qquad &//\ scale\ and\ shift
\mu_{\beta} &\gets \frac{1}{HW} \sum_{i=1}^{HW} x_i \qquad &//
\ mean\ of\ one\ feature\ map\ in\ mini-batch \\
\sigma_{\beta}^{2} &\gets \frac{1}{HW} \sum_{i=1}^{HW}(x_i -
\mu_{\beta})^2 \qquad &//\ variance\ of\ one\ feature\ map\ in\ mini-batch \\
\hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{
\sigma_{\beta}^{2} + \epsilon}} \qquad &//\ normalize \\
y_i &\gets \gamma \hat{x_i} + \beta \qquad &//\ scale\ and\ shift
Note:
`H` means height of feature map, `W` means width of feature map.
Expand Down Expand Up @@ -403,41 +403,42 @@ def data_norm(
.. math::
\\mu_{\\beta} &\\gets \\frac{1}{m} \\sum_{i=1}^{m} x_i \\qquad &//\\
\ mini-batch\ mean \\\\
\\sigma_{\\beta}^{2} &\\gets \\frac{1}{m} \\sum_{i=1}^{m}(x_i - \\
\\mu_{\\beta})^2 \\qquad &//\ mini-batch\ variance \\\\
\\hat{x_i} &\\gets \\frac{x_i - \\mu_\\beta} {\\sqrt{\\
\\sigma_{\\beta}^{2} + \\epsilon}} \\qquad &//\ normalize \\\\
y_i &\\gets \\gamma \\hat{x_i} + \\beta \\qquad &//\ scale\ and\ shift
\mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \qquad &//
\ mini-batch\ mean \\
\sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i -
\mu_{\beta})^2 \qquad &//\ mini-batch\ variance \\
\hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{
\sigma_{\beta}^{2} + \epsilon}} \qquad &//\ normalize \\
y_i &\gets \gamma \hat{x_i} + \beta \qquad &//\ scale\ and\ shift
Args:
input(Tensor): The input Tensor.
act(string, Default None): Activation type, linear|relu|prelu|...
epsilon(float, Default 1e-05):
param_attr(ParamAttr): The parameter attribute for Parameter `scale`.
input (Tensor): The input Tensor.
act (str, optional): Activation type, linear|relu|prelu|... Default: None.
epsilon(float, optional): Whether to add small values ​in​to the variance during calculations
to prevent division by zero. Default: 1e-05.
param_attr (ParamAttr, optional): The parameter attribute for Parameter `scale`. Default: None.
data_layout (str, optional): Specify the data format of the input, and the data format of the output
will be consistent with that of the input. An optional string from: `"NCHW"`, `"NHWC"`.
The default is `"NCHW"`. When it is `"NCHW"`, the data is stored in the order of:
`[batch_size, input_channels, input_height, input_width]`.
in_place(bool, Default False): Make the input and output of batch norm reuse memory.
name(string, Default None): A name for this layer(optional). If set None, the layer
will be named automatically.
moving_mean_name(string, Default None): The name of moving_mean which store the global Mean.
moving_variance_name(string, Default None): The name of the moving_variance which store the global Variance.
do_model_average_for_mean_and_var(bool, Default True): Whether parameter mean and variance
should do model average when model average is enabled.
slot_dim(int): The embedding dimension of one slot. Slot is a set of one specific feature. In pslib mode, we
distinguish feature ids by slot and pull their embeddings from parameter server (pslib). The first
`[batch_size, input_channels, input_height, input_width]`. Default: `"NCHW"`.
in_place (bool, optional): Make the input and output of batch norm reuse memory. Default: False.
name (str, optional): A name for this layer (optional). If set None, the layer
will be named automatically. Default: None.
moving_mean_name (str, optional): The name of moving_mean which store the global Mean. Default: None.
moving_variance_name (str, optional): The name of the moving_variance which store the global Variance. Default: None.
do_model_average_for_mean_and_var (bool, optional): Whether parameter mean and variance
should do model average when model average is enabled. Default: True.
slot_dim (int, optional): The embedding dimension of one slot. Slot is a set of one specific feature. In pslib mode,
we distinguish feature ids by slot and pull their embeddings from parameter server (pslib). The first
place of the embedding is the historical show number (occurence time of this feature id with a label 0).
If the input of this op is concated by slot-wise embeddings, and the show number is zero when this slot
is new or empty, the normalization result may be impractical. To avoid this, we add slot_dim to locate
the show number and judge if the show number is zero. If so, we choose to skip normalization on this
embedding.
sync_stats(bool, Default False): When running with multiple GPU cards, using allreduce to sync the
summary messages.
summary_decay_rate(float, Default 0.9999999): The decay rate when updating summary.
enable_scale_and_shift(bool, Default False): do scale&shift after normalization.
embedding. Default: -1.
sync_stats (bool, optional): When running with multiple GPU cards, using allreduce to sync the
summary messages. Default: False.
summary_decay_rate (float, optional): The decay rate when updating summary. Default: 0.9999999.
enable_scale_and_shift (bool, optional): do scale&shift after normalization. Default: False.
Returns:
Tensor: A tensor which is the result after applying data normalization on the input.
Expand Down Expand Up @@ -715,15 +716,15 @@ def conv3d(
.. math::
Out = \sigma (W \\ast X + b)
Out = \sigma (W \ast X + b)
In the above equation:
* :math:`X`: Input value, a tensor with NCDHW or NDHWC format.
* :math:`W`: Filter value, a tensor with MCDHW format.
* :math:`\\ast`: Convolution operation.
* :math:`\ast`: Convolution operation.
* :math:`b`: Bias value, a 2-D tensor with shape [M, 1].
* :math:`\\sigma`: Activation function.
* :math:`\sigma`: Activation function.
* :math:`Out`: Output value, the shape of :math:`Out` and :math:`X` may be different.
Example:
Expand All @@ -741,9 +742,9 @@ def conv3d(
.. math::
D_{out}&= \\frac{(D_{in} + 2 * paddings[0] - (dilations[0] * (D_f - 1) + 1))}{strides[0]} + 1 \\\\
H_{out}&= \\frac{(H_{in} + 2 * paddings[1] - (dilations[1] * (H_f - 1) + 1))}{strides[1]} + 1 \\\\
W_{out}&= \\frac{(W_{in} + 2 * paddings[2] - (dilations[2] * (W_f - 1) + 1))}{strides[2]} + 1
D_{out}&= \frac{(D_{in} + 2 * paddings[0] - (dilations[0] * (D_f - 1) + 1))}{strides[0]} + 1 \\
H_{out}&= \frac{(H_{in} + 2 * paddings[1] - (dilations[1] * (H_f - 1) + 1))}{strides[1]} + 1 \\
W_{out}&= \frac{(W_{in} + 2 * paddings[2] - (dilations[2] * (W_f - 1) + 1))}{strides[2]} + 1
Args:
input (Tensor): The input is 5-D Tensor with shape [N, C, D, H, W], the data
Expand Down Expand Up @@ -1027,15 +1028,15 @@ def conv2d_transpose(
.. math::
Out = \sigma (W \\ast X + b)
Out = \sigma (W \ast X + b)
Where:
* :math:`X`: Input value, a 4-D Tensor with NCHW or NHWC format.
* :math:`W`: Filter value, a 4-D Tensor with MCHW format.
* :math:`\\ast`: Convolution operation.
* :math:`\ast`: Convolution operation.
* :math:`b`: Bias value, a 2-D Tensor with shape [M, 1].
* :math:`\\sigma`: Activation function.
* :math:`\sigma`: Activation function.
* :math:`Out`: Output value, a 4-D Tensor with data format 'NCHW' or 'NHWC', the shape of :math:`Out` and :math:`X` may be different.
Example:
Expand All @@ -1054,9 +1055,9 @@ def conv2d_transpose(
.. math::
H^\prime_{out} &= (H_{in} - 1) * strides[0] - pad_height_top - pad_height_bottom + dilations[0] * (H_f - 1) + 1 \\\\
W^\prime_{out} &= (W_{in} - 1) * strides[1] - pad_width_left - pad_width_right + dilations[1] * (W_f - 1) + 1 \\\\
H_{out} &\in [ H^\prime_{out}, H^\prime_{out} + strides[0] ] \\\\
H^\prime_{out} &= (H_{in} - 1) * strides[0] - pad_height_top - pad_height_bottom + dilations[0] * (H_f - 1) + 1 \\
W^\prime_{out} &= (W_{in} - 1) * strides[1] - pad_width_left - pad_width_right + dilations[1] * (W_f - 1) + 1 \\
H_{out} &\in [ H^\prime_{out}, H^\prime_{out} + strides[0] ] \\
W_{out} &\in [ W^\prime_{out}, W^\prime_{out} + strides[1] ]
Note:
Expand Down Expand Up @@ -1416,11 +1417,11 @@ def conv3d_transpose(
.. math::
D^\prime_{out} &= (D_{in} - 1) * strides[0] - 2 * paddings[0] + dilations[0] * (D_f - 1) + 1 \\\\
H^\prime_{out} &= (H_{in} - 1) * strides[1] - 2 * paddings[1] + dilations[1] * (H_f - 1) + 1 \\\\
W^\prime_{out} &= (W_{in} - 1) * strides[2] - 2 * paddings[2] + dilations[2] * (W_f - 1) + 1 \\\\
D_{out} &\in [ D^\prime_{out}, D^\prime_{out} + strides[0] ] \\\\
H_{out} &\in [ H^\prime_{out}, H^\prime_{out} + strides[1] ] \\\\
D^\prime_{out} &= (D_{in} - 1) * strides[0] - 2 * paddings[0] + dilations[0] * (D_f - 1) + 1 \\
H^\prime_{out} &= (H_{in} - 1) * strides[1] - 2 * paddings[1] + dilations[1] * (H_f - 1) + 1 \\
W^\prime_{out} &= (W_{in} - 1) * strides[2] - 2 * paddings[2] + dilations[2] * (W_f - 1) + 1 \\
D_{out} &\in [ D^\prime_{out}, D^\prime_{out} + strides[0] ] \\
H_{out} &\in [ H^\prime_{out}, H^\prime_{out} + strides[1] ] \\
W_{out} &\in [ W^\prime_{out}, W^\prime_{out} + strides[2] ]
Note:
Expand Down Expand Up @@ -1777,8 +1778,8 @@ def deformable_conv(
.. math::
H_{out}&= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]} + 1 \\\\
W_{out}&= \\frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]} + 1
H_{out}&= \frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]} + 1 \\
W_{out}&= \frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]} + 1
Args:
input (Tensor): The input image with [N, C, H, W] format. A Tensor with type
Expand Down Expand Up @@ -2016,8 +2017,8 @@ def deform_conv2d(
.. math::
H_{out}&= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]} + 1 \\\\
W_{out}&= \\frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]} + 1
H_{out}&= \frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]} + 1 \\
W_{out}&= \frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]} + 1
Args:
x (Tensor): The input image with [N, C, H, W] format. A Tensor with type
Expand Down
4 changes: 2 additions & 2 deletions python/paddle/tensor/logic.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ def _logical_op(op_name, x, y, out=None, name=None, binary_op=True):
def logical_and(x, y, out=None, name=None):
r"""
``logical_and`` operator computes element-wise logical AND on ``x`` and ``y``, and returns ``out``. ``out`` is N-dim boolean ``Tensor``.
Compute element-wise logical AND on ``x`` and ``y``, and return ``out``. ``out`` is N-dim boolean ``Tensor``.
Each element of ``out`` is calculated by
.. math::
Expand All @@ -103,7 +103,7 @@ def logical_and(x, y, out=None, name=None):
Args:
x (Tensor): the input tensor, it's data type should be one of bool, int8, int16, in32, in64, float32, float64.
y (Tensor): the input tensor, it's data type should be one of bool, int8, int16, in32, in64, float32, float64.
out(Tensor): The ``Tensor`` that specifies the output of the operator, which can be any ``Tensor`` that has been created in the program. The default value is None, and a new ``Tensor`` will be created to save the output.
out(Tensor, optional): The ``Tensor`` that specifies the output of the operator, which can be any ``Tensor`` that has been created in the program. The default value is None, and a new ``Tensor`` will be created to save the output.
name (str, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`.
Returns:
Expand Down
2 changes: 1 addition & 1 deletion python/paddle/tensor/manipulation.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
def cast(x, dtype):
"""
This OP takes in the Tensor :attr:`x` with :attr:`x.dtype` and casts it
Take in the Tensor :attr:`x` with :attr:`x.dtype` and cast it
to the output with :attr:`dtype`. It's meaningless if the output dtype
equals the input dtype, but it's fine if you do so.
Expand Down

0 comments on commit dd900b3

Please # to comment.