Layer

    基于OOD实现的动态图Layer，包含该Layer的参数、前序运行的结构等信息。

    参数：

    • name_scope (str，可选) - 为Layer内部参数命名而采用的名称前缀。如果前缀为“mylayer”，在一个类名为MyLayer的Layer中，参数名为“mylayer_0.w_n”，其中w是参数的名称，n为自动生成的具有唯一性的后缀。如果为None，前缀名将为小写的类名。默认值为None。

    • dtype (str可选) - Layer中参数数据类型。如果设置为str，则可以是“bool”，“float16”，“float32”，“float64”，“int8”，“int16”，“int32”，“int64”，“uint8”或“uint16”。默认值为 “float32”。

    返回：无

    train ( )

    将此层及其所有子层设置为训练模式。这只会影响某些模块，如Dropout和BatchNorm。

    返回：无

    代码示例

    eval ( )

    将此层及其所有子层设置为预测模式。这只会影响某些模块，如Dropout和BatchNorm。

    返回：无

    代码示例

    1. import paddle
    3. class MyLayer(paddle.nn.Layer):
    4.     def __init__(self):
    5.         super(MyLayer, self).__init__()
    6.         self._linear = paddle.nn.Linear(1, 1)
    7.         self._dropout = paddle.nn.Dropout(p=0.5)
    9.     def forward(self, input):
    10.         temp = self._linear(input)
    11.         temp = self._dropout(temp)
    12.         return temp
    14. x = paddle.randn([10, 1], 'float32')
    15. mylayer = MyLayer()
    16. mylayer.eval()  # set mylayer._dropout to eval mode
    17. out = mylayer(x)
    18. print(out)

    full_name ( )

    Layer的全名。组成方式为： name_scope + “/” + MyLayer.__class__.__name__ 。

    返回：str， Layer的全名

    代码示例

    1. import paddle
    3. class LinearNet(paddle.nn.Layer):
    4.     def __init__(self):
    5.         super(LinearNet, self).__init__(name_scope = "demo_linear_net")
    6.         self._linear = paddle.nn.Linear(1, 1)
    8.     def forward(self, x):
    9.         return self._linear(x)
    11. linear_net = LinearNet()
    12. print(linear_net.full_name())   # demo_linear_net_0

    register_forward_pre_hook ( hook )

    为Layer注册一个 forward pre-hook 函数，该 hook 函数将会在 forward 函数调用之前被调用。

    hook 函数具有以下形式：它的 input 是 Layer 的 input ，并且可以返回一个元组或者单个修改值；如果返回单个修改值，则将值包装到一个元组中。用户可以使用该函数来查看或修改 Layer forward 函数的输入。

    hook(Layer, input) -> None or modified input

    参数：

    • hook (function) - 被注册为 forward pre-hook 的函数

    返回：HookRemoveHelper，可通过调用 hook_remove_helper.remove() 来删除注册的hook函数。

    代码示例

    1. import paddle
    2. import numpy as np
    4. # the forward_post_hook change the input of the layer: input = input * 2
    5. def forward_pre_hook(layer, input):
    6.     # user can use layer and input for information statistis tasks
    7.     # change the input
    8.     input_return = (input[0] * 2)
    9.     return input_return
    11. linear = paddle.nn.Linear(13, 5)
    12. # register the hook
    13. forward_pre_hook_handle = linear.register_forward_pre_hook(forward_pre_hook)
    14. value0 = np.arange(26).reshape(2, 13).astype("float32")
    15. in0 = paddle.to_tensor(value0)
    16. out0 = linear(in0)
    18. # remove the hook
    19. forward_pre_hook_handle.remove()
    20. value1 = value0 * 2
    21. in1 = paddle.to_tensor(value1)
    22. out1 = linear(in1)
    24. # hook change the linear's input to input * 2, so out0 is equal to out1.
    25. assert (out0.numpy() == out1.numpy()).any()

    register_forward_post_hook ( hook )

    为Layer注册一个 forward post-hook 函数，该 hook 函数将会在 forward 函数调用之后被调用。

    hook 函数具有以下形式，它的 input 和 output 是 Layer 的 input 和 output 。用户可以用该函数来查看和修改 Layer forward 函数的输出。

    hook(Layer, input, output) -> None or modified output

    参数：

    • hook (function) - 被注册为 forward post-hook 的函数

    返回：HookRemoveHelper，可通过调用 hook_remove_helper.remove() 来删除注册的hook函数。

    代码示例

    1. import paddle
    2. import numpy as np
    4. # the forward_post_hook change the output of the layer: output = output * 2
    5. def forward_post_hook(layer, input, output):
    6.     # user can use layer, input and output for information statistis tasks
    7.     # change the output
    8.     return output * 2
    10. linear = paddle.nn.Linear(13, 5)
    11. # register the hook
    12. forward_post_hook_handle = linear.register_forward_post_hook(forward_post_hook)
    13. value1 = np.arange(26).reshape(2, 13).astype("float32")
    14. in1 = paddle.to_tensor(value1)
    15. out0 = linear(in1)
    17. # remove the hook
    18. forward_post_hook_handle.remove()
    19. out1 = linear(in1)
    21. # hook change the linear's output to output * 2, so out0 is equal to out1 * 2.
    22. assert (out0.numpy() == (out1.numpy()) * 2).any()

    create_parameter ( shape, attr=None, dtype=’float32’, is_bias=False, default_initializer=None )

    为Layer创建参数。

    参数：

    • shape (list) - 参数的形状。列表中的数据类型必须为int。

    • attr (ParamAttr，可选) - 指定权重参数属性的对象，表示使用默认的权重参数属性。具体用法请参见 ParamAttr 。默认值为None。

    • dtype (str|core.VarDesc.VarType, 可选) - Layer中参数数据类型。如果设置为str，则可以是“bool”，“float16”，“float32”，“float64”，“int8”，“int16”，“int32”，“int64”，“uint8”或“uint16”。默认值为“float32”。

    • is_bias (bool, 可选) - 是否是偏置参数。默认值：False。

    • default_initializer (Initializer, 可选) - 默认的参数初始化方法。如果设置为None，则设置非bias参数的初始化方式为 paddle.nn.initializer.Xavier ，设置bias参数的初始化方式为 paddle.nn.initializer.Constant 。默认值：None。

    返回：Tensor， 创建的参数变量

    代码示例

    1. import paddle
    3. class MyLayer(paddle.nn.Layer):
    4.     def __init__(self):
    5.         super(MyLayer, self).__init__()
    6.         self._linear = paddle.nn.Linear(1, 1)
    7.         w_tmp = self.create_parameter([1,1])
    8.         self.add_parameter("w_tmp", w_tmp)
    9.     def forward(self, input):
    10.         return self._linear(input)
    12. mylayer = MyLayer()
    13. for name, param in mylayer.named_parameters():
    14.     print(name, param)      # will print w_tmp,_linear.weight,_linear.bias

    create_variable ( name=None, persistable=None, dtype=None )

    为Layer创建变量。

    参数：

    • name (str, 可选) - 变量名。默认值：None。

    • persistable (bool, 可选) - 是否为持久性变量，后续会被移出。默认值：None。

    • dtype (str, 可选) - Layer中参数数据类型。如果设置为str，则可以是“bool”，“float16”，“float32”，“float64”，“int8”，“int16”，“int32”，“int64”，“uint8”或“uint16”。默认值为 “float32” 。

    返回：Tensor， 返回创建的 Tensor

    代码示例

    1. import paddle
    3. class MyLinear(paddle.nn.Layer):
    4.     def __init__(self,
    5.                 in_features,
    6.                 out_features):
    7.         super(MyLinear, self).__init__()
    8.         self.linear = paddle.nn.Linear( 10, 10)
    10.         self.back_var = self.create_variable(name = "linear_tmp_0", dtype=self._dtype)
    12.     def forward(self, input):
    13.         out = self.linear(input)
    14.         paddle.assign( out, self.back_var)
    16.         return out

    create_tensor ( name=None, persistable=None, dtype=None )

    参数：

    • name (str, 可选) - 变量名。默认值：None。

    • persistable (bool, 可选) - 是否为持久性变量，后续会被移出。默认值：None。

    • dtype (str, 可选) - Layer中参数数据类型。如果设置为str，则可以是“bool”，“float16”，“float32”，“float64”，“int8”，“int16”，“int32”，“int64”，“uint8”或“uint16”。默认值为 “float32” 。

    返回：Tensor， 返回创建的 Tensor

    代码示例

    parameters ( include_sublayers=True )

    返回一个由当前层及其子层的所有参数组成的列表。

    参数：

    • include_sublayers (bool, 可选) - 是否返回子层的参数。如果为True，返回的列表中包含子层的参数。默认值：True。

    返回：list， 一个由当前层及其子层的所有参数组成的列表，列表中的元素类型为Parameter(Tensor)。

    代码示例

    1. import paddle
    3. linear = paddle.nn.Linear(1,1)
    4. print(linear.parameters())  # print linear_0.w_0 and linear_0.b_0

    children ( )

    返回所有子层的迭代器。

    返回：iterator， 子层的迭代器。

    代码示例

    1. import paddle
    3. linear1 = paddle.nn.Linear(10, 3)
    4. linear2 = paddle.nn.Linear(3, 10, bias_attr=False)
    5. model = paddle.nn.Sequential(linear1, linear2)
    7. layer_list = list(model.children())
    9. print(layer_list)   # [<paddle.nn.layer.common.Linear object at 0x7f7b8113f830>, <paddle.nn.layer.common.Linear object at 0x7f7b8113f950>]

    named_children ( )

    返回所有子层的迭代器，生成子层名称和子层的元组。

    返回：iterator， 产出子层名称和子层的元组的迭代器。

    代码示例

    1. import paddle
    3. linear1 = paddle.nn.Linear(10, 3)
    4. linear2 = paddle.nn.Linear(3, 10, bias_attr=False)
    5. model = paddle.nn.Sequential(linear1, linear2)
    6. for prefix, layer in model.named_children():
    7.     print(prefix, layer)
    8.     # ('0', <paddle.nn.layer.common.Linear object at 0x7fb61ed85830>)
    9.     # ('1', <paddle.nn.layer.common.Linear object at 0x7fb61ed85950>)

    sublayers ( include_sublayers=True )

    返回一个由所有子层组成的列表。

    参数：

    • include_sublayers (bool, 可选) - 是否返回子层中各个子层。如果为True，则包括子层中的各个子层。默认值：True。

    返回： list， 一个由所有子层组成的列表，列表中的元素类型为Layer。

    代码示例

    1. import paddle
    3. class MyLayer(paddle.nn.Layer):
    4.     def __init__(self):
    5.         super(MyLayer, self).__init__()
    6.         self._linear = paddle.nn.Linear(1, 1)
    7.         self._dropout = paddle.nn.Dropout(p=0.5)
    9.     def forward(self, input):
    10.         temp = self._linear(input)
    11.         temp = self._dropout(temp)
    12.         return temp
    14. mylayer = MyLayer()
    15. print(mylayer.sublayers())  # [<paddle.nn.layer.common.Linear object at 0x7f44b58977d0>, <paddle.nn.layer.common.Dropout object at 0x7f44b58978f0>]

    clear_gradients ( )

    清除该层所有参数的梯度。

    返回：无

    代码示例

    1. import paddle
    2. import numpy as np
    4. value = np.arange(26).reshape(2, 13).astype("float32")
    5. a = paddle.to_tensor(value)
    6. linear = paddle.nn.Linear(13, 5)
    7. adam = paddle.optimizer.Adam(learning_rate=0.01,
    8.                             parameters=linear.parameters())
    9. out = linear(a)
    10. out.backward()
    11. adam.step()
    12. linear.clear_gradients()

    named_parameters ( prefix=’’, include_sublayers=True )

    返回层中所有参数的迭代器，生成名称和参数的元组。

    参数：

    • prefix (str, 可选) - 在所有参数名称前加的前缀。默认值：’’。

    • include_sublayers (bool, 可选) - 是否返回子层的参数。如果为True，返回的列表中包含子层的参数。默认值：True。

    返回：iterator， 产出名称和参数的元组的迭代器。

    代码示例

    1. import paddle
    3. fc1 = paddle.nn.Linear(10, 3)
    5. model = paddle.nn.Sequential(fc1, fc2)
    6. for name, param in model.named_parameters():
    7.     print(name, param)

    named_sublayers ( prefix=’’, include_sublayers=True, include_self=False, layers_set=None )

    返回层中所有子层上的迭代器，生成名称和子层的元组。重复的子层只产生一次。

    参数：

    • prefix (str, 可选) - 在所有参数名称前加的前缀。默认值：’’。

    • include_sublayers (bool, 可选) - 是否返回子层中各个子层。如果为True，则包括子层中的各个子层。默认值：True。

    • include_self (bool, 可选) - 是否包含该层自身。默认值：False。

    • layers_set (set, 可选): 记录重复子层的集合。默认值：None。

    返回：iterator， 产出名称和子层的元组的迭代器。

    代码示例

    register_buffer ( name, tensor, persistable=True )

    将一个Tensor注册为buffer。

    buffer是一个不可训练的变量，不会被优化器更新，但在评估或预测阶段可能是必要的状态变量。比如 BatchNorm 中的均值和方差。

    注册的buffer默认是可持久性的，会被保存到 state_dict 中。如果指定 persistable 参数为False，则会注册一个非持久性的buffer，即不会同步和保存到 state_dict 中。

    参数：

    • name (str) - 注册buffer的名字。可以通过此名字来访问已注册的buffer。

    返回：None

    代码示例

    1. import numpy as np
    2. import paddle
    4. linear = paddle.nn.Linear(10, 3)
    5. value = np.array([0]).astype("float32")
    6. buffer = paddle.to_tensor(value)
    7. linear.register_buffer("buf_name", buffer, persistable=True)
    8. # get the buffer by attribute.
    9. print(linear.buf_name)

    buffers ( include_sublayers=True )

    返回一个由当前层及其子层的所有buffers组成的列表。

    参数：

    • include_sublayers (bool, 可选) - 是否返回子层的buffers。如果为True，返回的列表中包含子层的buffers。默认值：True。

    返回：list， 一个由当前层及其子层的所有buffers组成的列表，列表中的元素类型为Tensor。

    代码示例

    1. import numpy as np
    2. import paddle
    4. linear = paddle.nn.Linear(10, 3)
    5. value = np.array([0]).astype("float32")
    6. buffer = paddle.to_tensor(value)
    7. linear.register_buffer("buf_name", buffer, persistable=True)
    9. print(linear.buffers())     # == print([linear.buf_name])

    named_buffers ( prefix=’’, include_sublayers=True )

    返回层中所有buffers的迭代器，生成名称和buffer的元组。

    参数：

    • prefix (str, 可选) - 在所有buffer名称前加的前缀。默认值：’’。

    • include_sublayers (bool, 可选) - 是否返回子层的buffers。如果为True，返回的列表中包含子层的buffers。默认值：True。

    返回：iterator， 产出名称和buffer的元组的迭代器。

    代码示例

    1. import numpy as np
    2. import paddle
    4. fc1 = paddle.nn.Linear(10, 3)
    5. buffer1 = paddle.to_tensor(np.array([0]).astype("float32"))
    6. # register a tensor as buffer by specific `persistable`
    7. fc1.register_buffer("buf_name_1", buffer1, persistable=True)
    9. fc2 = paddle.nn.Linear(3, 10)
    10. buffer2 = paddle.to_tensor(np.array([1]).astype("float32"))
    11. # register a buffer by assigning an attribute with Tensor.
    12. # The `persistable` can only be False by this way.
    13. fc2.buf_name_2 = buffer2
    15. model = paddle.nn.Sequential(fc1, fc2)
    17. # get all named buffers
    18. for name, buffer in model.named_buffers():
    19.     print(name, buffer)

    forward ( \inputs, **kwargs* )

    定义每次调用时执行的计算。应该被所有子类覆盖。

    参数：

    • *inputs (tuple) - 解包后的tuple参数。

    • **kwargs (dict) - 解包后的dict参数。

    返回： 无

    add_sublayer ( name, sublayer )

    添加子层实例。可以通过self.name访问该sublayer。

    参数：

    • name (str) - 子层名。

    • sublayer (Layer) - Layer实例。

    返回：Layer， 添加的子层

    代码示例

    1. import paddle
    3. class MySequential(paddle.nn.Layer):
    4.     def __init__(self, *layers):
    5.         super(MySequential, self).__init__()
    6.         if len(layers) > 0 and isinstance(layers[0], tuple):
    7.             for name, layer in layers:
    8.                 self.add_sublayer(name, layer)
    9.         else:
    10.             for idx, layer in enumerate(layers):
    11.                 self.add_sublayer(str(idx), layer)
    13.     def forward(self, input):
    14.         for layer in self._sub_layers.values():
    15.             input = layer(input)
    16.         return input
    18. fc1 = paddle.nn.Linear(10, 3)
    19. fc2 = paddle.nn.Linear(3, 10, bias_attr=False)
    20. model = MySequential(fc1, fc2)
    21. for prefix, layer in model.named_sublayers():
    22.     print(prefix, layer)

    add_parameter ( name, parameter )

    添加参数实例。可以通过self.name访问该parameter。

    参数：

    • name (str) - 参数名。

    • parameter (Parameter) - Parameter实例。

    返回：Parameter， 传入的参数实例

    代码示例

    1. import paddle
    3. class MyLayer(paddle.nn.Layer):
    4.     def __init__(self):
    5.         super(MyLayer, self).__init__()
    6.         self._linear = paddle.nn.Linear(1, 1)
    7.         w_tmp = self.create_parameter([1,1])
    8.         self.add_parameter("w_tmp", w_tmp)
    10.     def forward(self, input):
    11.         return self._linear(input)
    13. mylayer = MyLayer()
    14. for name, param in mylayer.named_parameters():
    15.     print(name, param)      # will print w_tmp,_linear.weight,_linear.bias

    state_dict ( destination=None, include_sublayers=True )

    获取当前层及其子层的所有参数和可持久性buffers。并将所有参数和buffers存放在dict结构中。

    参数：

    • destination (dict, 可选) - 如果提供 destination ，则所有参数和可持久性buffers都将存放在 destination 中。 默认值：None。

    • include_sublayers (bool, 可选) - 如果设置为True，则包括子层的参数和buffers。默认值：True。

    返回：dict， 包含所有参数和可持久行buffers的dict

    代码示例

    1. import paddle
    3. emb = paddle.nn.Embedding(10, 10)
    5. state_dict = emb.state_dict()
    6. paddle.save( state_dict, "paddle_dy.pdparams")

    set_state_dict ( state_dict, include_sublayers=True, use_structured_name=True )

    根据传入的 state_dict 设置参数和可持久性buffers。 所有参数和buffers将由 中的 Tensor 设置。

    参数：

    • state_dict (dict) - 包含所有参数和可持久性buffers的dict。

    • include_sublayers (bool, 可选) - 如果设置为True，则还包括子层的参数和buffers。 默认值：True。

    • use_structured_name (bool, 可选) - 如果设置为True，将使用Layer的结构性变量名作为dict的key，否则将使用Parameter或者Buffer的变量名作为key。默认值：True。

    返回：无

    代码示例