pad

paddle.nn.functional. pad ( x: Tensor, pad: ShapeLike, mode: _PaddingTensorMode = 'constant', value: float = 0.0, data_format: DataLayoutND | None = None, pad_from_left_axis: bool = True, name: str | None = None ) → Tensor [source]

Pad tensor according to 'pad' and 'mode'.

Note

1. Denote 'x'’s dimension as N (same in the following). If mode is 'constant', the length of 'pad' can be any even number less than or equal to 2*N.

2. When mode is 'constant', and 'pad' is a list or tuple, and the length of 'pad' is not equal to 2*(N - 2): 2.1. If the length of 'pad' is 2*N, the order of padding can be customized by 'pad_from_left_axis'. if 'pad_from_left_axis' is True, then the padding order will be started from the first dimension of 'x' and moving backward according to 'pad'; else if 'pad_from_left_axis' is False, then the padding order will be started from the last dimension of 'x' and moving forward according to 'pad'. 2.2. Otherwise, the padding will be started from the last dimension.

3. When mode is any of 'reflect', 'replicate', 'circular', or 'pad' is a tensor, or the length of 'pad' is 2*(N - 2), and the dimension of 'x' only supports 3-D, 4-D and 5-D. In these cases, input 'x' will be padded on [D, H, W] axes according to 'data_format'. It will pad from the last dimension to the first dimension of [D, H, W] axes. Specifically, if N = 3, then the pad has the form (pad_left, pad_right); if N = 4, then the pad has the form (pad_left, pad_right, pad_top, pad_bottom); if N = 5, then the pad has the form (pad_left, pad_right, pad_top, pad_bottom, pad_front, pad_back).

4. If mode is 'reflect', pad[0] and pad[1] must be no greater than width-1. The height and depth dimension has the same condition.

Parameters

  • x (Tensor) – The input tensor with data type float32, float64, int32, int64, complex64 or complex128.

  • pad (Tensor|list[int]|tuple[int]) – The padding size with data type int. Refer to Note for details.

  • mode (str, optional) –

    Four modes: 'constant' (default), 'reflect', 'replicate', 'circular'. Default is 'constant'.

    • ’constant’ mode, uses a constant value to pad the input tensor.

    • ’reflect’ mode, uses reflection of the input boundaries to pad the input tensor.

    • ’replicate’ mode, uses input boundaries to pad the input tensor.

    • ’circular’ mode, uses circular input to pad the input tensor.

  • value (float, optional) – The value to fill the padded areas in ‘constant’ mode . Default is \(0.0\).

  • data_format (str, optional) – An string from: 'NCL', 'NLC', 'NHWC', 'NCHW', 'NCDHW', 'NDHWC'. Specify the data format of the input data when: 1. mode is any of 'reflect', 'replicate' or 'circular'; or 2. the input 'pad' is a tensor; or 3. the length of 'pad' is 2*(x.ndim - 2). The default value is None, which means it will be automatically inferred from the input dimension of 'x'. When 'x' is a 3-D Tensor, data_format will be set to 'NCL'; When 'x' is a 4-D Tensor, data_format will be set to 'NCHW'; When 'x' is a 5-D Tensor, data_format will be set to 'NCDHW'.

  • pad_from_left_axis (bool, optional) – The parameter is only valid when mode is 'constant' and the input 'pad' is length of 'pad' is 2*x.ndim, the order of padding can be customized. If True, the padding will be started from the first axis of 'x'; if False, it will be started from the last axis of 'x'. Default: True.

  • name (str|None, optional) – For details, please refer to Name. Generally, no setting is required. Default: 'None'.

Returns

Tensor, a Tensor padded according to pad and mode and data type is same as input.

Example

x = [[[[[1., 2., 3.],
        [4., 5., 6.]]]]]

Case 0:
    pad = [0, 0, 0, 0, 0, 0, 1, 1, 0, 0],
    mode = 'constant'
    value = 0
    pad_from_left_axis = True
    Out = [[[[[0., 0., 0.],
              [1., 2., 3.],
              [4., 5., 6.],
              [0., 0., 0.]]]]]
    Out.shape = [1, 1, 1, 4, 3]

Case 1:
    pad = [0, 0, 0, 0, 0, 0, 1, 1, 0, 0],
    mode = 'constant'
    value = 0
    pad_from_left_axis = False
    Out = [[[[[0., 0., 0.],
              [0., 0., 0.]]],
            [[[1., 2., 3.],
              [4., 5., 6.]]],
            [[[0., 0., 0.],
              [0., 0., 0.]]]]]
    Out.shape = [1, 3, 1, 2, 3]

Case 3:
    pad = [1, 0, 0, 1],
    mode = 'constant'
    value = 0
    Out = [[[[[0., 1., 2., 3.],
              [0., 4., 5., 6.],
              [0., 0., 0., 0.]]]]]
    Out.shape = [1, 1, 1, 3, 4]

Case 4:
    pad = [2, 2, 1, 1, 0, 0],
    mode = 'constant'
    value = 0
    Out = [[[[[0. 0. 0. 0. 0. 0. 0.]
              [0. 0. 1. 2. 3. 0. 0.]
              [0. 0. 4. 5. 6. 0. 0.]
              [0. 0. 0. 0. 0. 0. 0.]]]]]
    Out.shape = [1, 1, 1, 4, 7]

Case 5:
    pad = [2, 2, 1, 1, 0, 0],
    mode = 'reflect'
    Out = [[[[[6. 5. 4. 5. 6. 5. 4.]
              [3. 2. 1. 2. 3. 2. 1.]
              [6. 5. 4. 5. 6. 5. 4.]
              [3. 2. 1. 2. 3. 2. 1.]]]]]
    Out.shape = [1, 1, 1, 4, 7]

Case 6:
    pad = [2, 2, 1, 1, 0, 0],
    mode = 'replicate'
    Out = [[[[[1. 1. 1. 2. 3. 3. 3.]
              [1. 1. 1. 2. 3. 3. 3.]
              [4. 4. 4. 5. 6. 6. 6.]
              [4. 4. 4. 5. 6. 6. 6.]]]]]
    Out.shape = [1, 1, 1, 4, 7]

Case 7:
    pad = [2, 2, 1, 1, 0, 0],
    mode = 'circular'
    Out = [[[[[5. 6. 4. 5. 6. 4. 5.]
              [2. 3. 1. 2. 3. 1. 2.]
              [5. 6. 4. 5. 6. 4. 5.]
              [2. 3. 1. 2. 3. 1. 2.]]]]]
    Out.shape = [1, 1, 1, 4, 7]

Examples

>>> import paddle
>>> import paddle.nn.functional as F

>>> # example 1
>>> x_shape = (1, 1, 3)
>>> x = paddle.arange(paddle.prod(paddle.to_tensor(x_shape)), dtype="float32").reshape(x_shape) + 1
>>> y = F.pad(x, [0, 0, 0, 0, 2, 3], value=1, mode='constant', data_format="NCL")
>>> print(y)
Tensor(shape=[1, 1, 8], dtype=float32, place=Place(cpu), stop_gradient=True,
[[[1., 1., 1., 2., 3., 1., 1., 1.]]])

>>> # example 2
>>> x_shape = (1, 1, 3)
>>> x = paddle.arange(paddle.prod(paddle.to_tensor(x_shape)), dtype="float32").reshape(x_shape) + 1
>>> y = F.pad(x, [2, 3], value=1, mode='constant', data_format="NCL")
>>> print(y)
Tensor(shape=[1, 1, 8], dtype=float32, place=Place(cpu), stop_gradient=True,
[[[1., 1., 1., 2., 3., 1., 1., 1.]]])

>>> # example 3
>>> x_shape = (1, 1, 2, 3)
>>> x = paddle.arange(paddle.prod(paddle.to_tensor(x_shape)), dtype="float32").reshape(x_shape) + 1
>>> y = F.pad(x, [1, 2, 1, 1], value=1, mode='circular')
>>> print(y)
Tensor(shape=[1, 1, 4, 6], dtype=float32, place=Place(cpu), stop_gradient=True,
[[[[6., 4., 5., 6., 4., 5.],
   [3., 1., 2., 3., 1., 2.],
   [6., 4., 5., 6., 4., 5.],
   [3., 1., 2., 3., 1., 2.]]]])

>>> # example 4
>>> x_shape = (1, 1, 3)
>>> x = paddle.arange(paddle.prod(paddle.to_tensor(x_shape)), dtype="float32").reshape(x_shape) + 1
>>> y = F.pad(x, [1, 0, 0, 1, 0, 0], value=0, mode='constant', pad_from_left_axis=True)
>>> print(y)
Tensor(shape=[2, 2, 3], dtype=float32, place=Place(cpu), stop_gradient=True,
[[[0., 0., 0.],
  [0., 0., 0.]],
 [[1., 2., 3.],
  [0., 0., 0.]]])

>>> # example 5
>>> x_shape = (1, 1, 3)
>>> x = paddle.arange(paddle.prod(paddle.to_tensor(x_shape)), dtype="float32").reshape(x_shape) + 1
>>> y = F.pad(x, [1, 0, 0, 1, 0, 0], value=0, mode='constant', pad_from_left_axis=False)
>>> print(y)
Tensor(shape=[1, 2, 4], dtype=float32, place=Place(cpu), stop_gradient=True,
[[[0., 1., 2., 3.],
  [0., 0., 0., 0.]]])

>>> # example 6
>>> x_shape = (1, 1, 3)
>>> x = paddle.arange(paddle.prod(paddle.to_tensor(x_shape)), dtype="float32").reshape(x_shape) + 1
>>> y = F.pad(x, [1, 0, 0, 1], value=0, mode='constant')
>>> print(y)
Tensor(shape=[1, 2, 4], dtype=float32, place=Place(cpu), stop_gradient=True,
[[[0., 1., 2., 3.],
  [0., 0., 0., 0.]]])