diff --git a/doc/paddle/api/paddle/compat/round_cn.rst b/doc/paddle/api/paddle/compat/round_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..0e5eed214ae6a74521e030803a36525c21e2820b --- /dev/null +++ b/doc/paddle/api/paddle/compat/round_cn.rst @@ -0,0 +1,31 @@ +.. _cn_api_tensor_cn_round: + +round +------------------------------- + +.. py:function:: paddle.round(x, name=None) + + + +该OP将输入中的数值四舍五入到最接近的整数数值。 + +参数: + - **x** (Tensor) - 输入的 `Tensor` ，数据类型为： float16, float32, float64。 + - **name** (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回： + - Tensor，对输入x四舍五入后的Tensor，形状、数据类型与输入x一致。 + + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + paddle.disable_static() + x_data = np.array([-0.5, -0.2, 0.6, 1.5]) + x = paddle.to_tensor(x_data) + out = paddle.round(x) + print(out.numpy()) + # [-1. -0. 1. 2.] diff --git a/doc/paddle/api/paddle/dataset/Conll05_cn.rst b/doc/paddle/api/paddle/dataset/Conll05_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..4aed0c84ead74ff9b52f83982509d4c6aa4462a7 --- /dev/null +++ b/doc/paddle/api/paddle/dataset/Conll05_cn.rst @@ -0,0 +1,31 @@ +.. _cn_api_paddle_dataset_Conll05: + +Conll05 +------------------------------- + +Conll05数据集。Paddle深度学习基础中的语义角色标注文档使用这个数据集为例。因为Conll05数据集不是免费公开的，所以默认下载的url是Conll05的测试集（它是公开的）。用户可以将url和md5更改为其Conll数据集。并采用基于维基百科语料库的预训练词向量模型对SRL模型进行初始化。 + + +.. py:function:: paddle.dataset.conll05.get_dict() + +获取维基百科语料库的单词、动词和标签字典。 + + +.. py:function:: paddle.dataset.conll05.get_embedding() + +获取基于维基百科语料库的训练词向量。 + + + +.. py:function:: paddle.dataset.conll05.test() + +Conll05测试数据集的creator。 + +因为训练数据集不是免费公开的，所以用测试数据集进行训练。它返回一个reader creator，reader中的每个样本都有九个特征，包括句子序列、谓词、谓词上下文、谓词上下文标记和标记序列。 + +返回： 训练数据集的reader creator + +返回类型：callable + + + diff --git a/doc/paddle/api/paddle/dataset/common/split_cn.rst b/doc/paddle/api/paddle/dataset/common/split_cn.rst index ca1607ee55c07488cd3a343ec72bf5c216ae2614..d7421732749cd2cb0892d98371d2ca6d0da50540 100644 --- a/doc/paddle/api/paddle/dataset/common/split_cn.rst +++ b/doc/paddle/api/paddle/dataset/common/split_cn.rst @@ -1,65 +1,52 @@ -.. _cn_api_fluid_layers_split: - +.. _cn_api_paddle_tensor_split split ------------------------------- -.. py:function:: paddle.fluid.layers.split(input, num_or_sections, dim=-1, name=None) - +.. py:function:: paddle.tensor.split(x, num_or_sections, axis=0, name=None) 该OP将输入Tensor分割成多个子Tensor。 -参数： - - **input** (Tensor) - 输入变量，数据类型为bool， float16，float32，float64，int32，int64的多维Tensor。 - - **num_or_sections** (int|list|tuple) - 如果 ``num_or_sections`` 是一个整数，则表示Tensor平均划分为相同大小子Tensor的数量。如果 ``num_or_sections`` 是一个list或tuple，那么它的长度代表子Tensor的数量，它的元素可以是整数或者形状为[1]的Tensor，依次代表子Tensor需要分割成的维度的大小。list或tuple的长度不能超过输入Tensor待分割的维度的大小。至多有一个元素值为-1，-1表示该值是由 ``input`` 待分割的维度值和 ``num_or_sections`` 的剩余元素推断出来的。 - - **dim** (int|Tenspr，可选) - 整数或者形状为[1]的Tensor，数据类型为int32或int64。表示需要分割的维度。如果 ``dim < 0`` ，则划分的维度为 ``rank(input) + dim`` 。默认值为-1。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 +**参数**： + - **x** (Tensor) - 输入变量，数据类型为bool, float16, float32，float64，int32，int64的多维Tensor。 + - **num_or_sections** (int|list|tuple) - 如果 ``num_or_sections`` 是一个整数，则表示Tensor平均划分为相同大小子Tensor的数量。如果 ``num_or_sections`` 是一个list或tuple，那么它的长度代表子Tensor的数量，它的元素可以是整数或者形状为[1]的Tensor，依次代表子Tensor需要分割成的维度的大小。list或tuple的长度不能超过输入Tensor待分割的维度的大小。在list或tuple中，至多有一个元素值为-1，表示该值是由 ``x`` 的维度和其他 ``num_or_sections`` 中元素推断出来的。例如对一个维度为[4,6,6]Tensor的第三维进行分割时，指定 ``num_or_sections=[2,-1,1]`` ，输出的三个Tensor维度分别为：[4,6,2]，[4,6,3]，[4,6,1]。 + - **axis** (int|Tensor，可选) - 整数或者形状为[1]的Tensor，数据类型为int32或int64。表示需要分割的维度。如果 ``axis < 0`` ，则划分的维度为 ``rank(x) + axis`` 。默认值为0。 + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回：分割后的Tensor列表。 -抛出异常： - - :code:`TypeError`：``input`` 的数据类型不是bool、float16、float32、float64、int32或int64时 。 - - :code:`TypeError`：``num_or_sections`` 不是int、list 或 tuple时。 - - :code:`TypeError`：``dim`` 不是 int 或 Tensor时。当 ``dim`` 为Tensor，其数据类型不是int32或int64时。 - **代码示例**： .. code-block:: python - import paddle.fluid as fluid - - # input is a Tensor which shape is [3, 9, 5] - input = fluid.data( - name="input", shape=[3, 9, 5], dtype="float32") + import numpy as np + import paddle + + paddle.disable_static() + # x is a Tensor which shape is [3, 9, 5] + x_np = np.random.random([3, 9, 5]).astype("int32") + x = paddle.to_tensor(x_np) - out0, out1, out2 = fluid.layers.split(input, num_or_sections=3, dim=1) + out0, out1, out22 = paddle.split(x, num_or_sections=3, axis=1) # out0.shape [3, 3, 5] # out1.shape [3, 3, 5] # out2.shape [3, 3, 5] - out0, out1, out2 = fluid.layers.split(input, num_or_sections=[2, 3, 4], dim=1) + out0, out1, out2 = paddle.split(x, num_or_sections=[2, 3, 4], axis=1) # out0.shape [3, 2, 5] # out1.shape [3, 3, 5] # out2.shape [3, 4, 5] - out0, out1, out2 = fluid.layers.split(input, num_or_sections=[2, 3, -1], dim=1) + out0, out1, out2 = paddle.split(x, num_or_sections=[2, 3, -1], axis=1) # out0.shape [3, 2, 5] # out1.shape [3, 3, 5] # out2.shape [3, 4, 5] - # dim is negative, the real dim is (rank(input) + axis) which real + # axis is negative, the real axis is (rank(x) + axis) which real # value is 1. - out0, out1, out2 = fluid.layers.split(input, num_or_sections=3, dim=-2) + out0, out1, out2 = paddle.split(x, num_or_sections=3, axis=-2) # out0.shape [3, 3, 5] # out1.shape [3, 3, 5] # out2.shape [3, 3, 5] - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/dygraph/parallel/ParallelEnv_cn.rst b/doc/paddle/api/paddle/distributed/ParallelEnv_cn.rst similarity index 100% rename from doc/paddle/api/paddle/fluid/dygraph/parallel/ParallelEnv_cn.rst rename to doc/paddle/api/paddle/distributed/ParallelEnv_cn.rst diff --git a/doc/paddle/api/paddle/distributed/all_gather_cn.rst b/doc/paddle/api/paddle/distributed/all_gather_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..6cbe19db63cad604c75657c9da83b18951475fdc --- /dev/null +++ b/doc/paddle/api/paddle/distributed/all_gather_cn.rst @@ -0,0 +1,44 @@ +.. _cn_api_distributed_all_gather: + +all_gather +------------------------------- + + +.. py:function:: paddle.distributed.all_gather(tensor_list, tensor, group=0) + +进程组内所有进程的指定tensor进行聚合操作，并返回给所有进程聚合的结果。 + +参数 +::::::::: + - tensor_list (list) - 操作的输出Tensor列表。列表中的每个元素均为Tensor，每个Tensor的数据类型为：float16、float32、float64、int32、int64。 + - tensor (Tensor) - 操作的输入Tensor。Tensor的数据类型为：float16、float32、float64、int32、int64。 + - group (int，可选) - 工作的进程组编号，默认为0。 + +返回 +::::::::: +无 + +代码示例 +::::::::: +.. code-block:: python + + import numpy as np + import paddle + from paddle.distributed import init_parallel_env + + paddle.disable_static() + paddle.set_device('gpu:%d'%paddle.distributed.ParallelEnv().dev_id) + init_parallel_env() + tensor_list = [] + if paddle.distributed.ParallelEnv().local_rank == 0: + np_data1 = np.array([[4, 5, 6], [4, 5, 6]]) + np_data2 = np.array([[4, 5, 6], [4, 5, 6]]) + data1 = paddle.to_tensor(np_data1) + data2 = paddle.to_tensor(np_data2) + paddle.distributed.all_gather(tensor_list, data1) + else: + np_data1 = np.array([[1, 2, 3], [1, 2, 3]]) + np_data2 = np.array([[1, 2, 3], [1, 2, 3]]) + data1 = paddle.to_tensor(np_data1) + data2 = paddle.to_tensor(np_data2) + paddle.distributed.all_gather(tensor_list, data2) diff --git a/doc/paddle/api/paddle/distributed/all_reduce_cn.rst b/doc/paddle/api/paddle/distributed/all_reduce_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..fc183c32190520eafa94e715dfc1a4822f80e54a --- /dev/null +++ b/doc/paddle/api/paddle/distributed/all_reduce_cn.rst @@ -0,0 +1,40 @@ +.. _cn_api_distributed_all_reduce: + +all_reduce +------------------------------- + + +.. py:function:: paddle.distributed.all_reduce(tensor, op=ReduceOp.SUM, group=0) + +进程组内所有进程的指定tensor进行归约操作，并返回给所有进程归约的结果。 + +参数 +::::::::: + - tensor (Tensor) - 操作的输入Tensor，同时也会将归约结果返回至此Tensor中。Tensor的数据类型为：float16、float32、float64、int32、int64。 + - op (ReduceOp.SUM|ReduceOp.MAX|ReduceOp.Min|ReduceOp.PROD，可选) - 归约的具体操作，比如求和，取最大值，取最小值和求乘积，默认为求和归约。 + - group (int，可选) - 工作的进程组编号，默认为0。 + +返回 +::::::::: +无 + +代码示例 +::::::::: +.. code-block:: python + + import numpy as np + import paddle + from paddle.distributed import ReduceOp + from paddle.distributed import init_parallel_env + + paddle.disable_static() + paddle.set_device('gpu:%d'%paddle.distributed.ParallelEnv().dev_id) + init_parallel_env() + if paddle.distributed.ParallelEnv().local_rank == 0: + np_data = np.array([[4, 5, 6], [4, 5, 6]]) + else: + np_data = np.array([[1, 2, 3], [1, 2, 3]]) + data = paddle.to_tensor(np_data) + paddle.distributed.all_reduce(data) + out = data.numpy() + # [[5, 7, 9], [5, 7, 9]] diff --git a/doc/paddle/api/paddle/distributed/barrier_cn.rst b/doc/paddle/api/paddle/distributed/barrier_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..fb63526cfd0163cec91396144b2e0c3c0f9beace --- /dev/null +++ b/doc/paddle/api/paddle/distributed/barrier_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_distributed_barrier: + +barrier +------------------------------- + + +.. py:function:: paddle.distributed.barrier(group=0) + +同步进程组内的所有进程。 + +参数 +::::::::: + - group (int，可选) - 工作的进程组编号，默认为0。 + +返回 +::::::::: +无 + +代码示例 +::::::::: +.. code-block:: python + + import paddle + from paddle.distributed import init_parallel_env + + paddle.disable_static() + paddle.set_device('gpu:%d'%paddle.distributed.ParallelEnv().dev_id) + init_parallel_env() + paddle.distributed.barrier() diff --git a/doc/paddle/api/paddle/distributed/broadcast_cn.rst b/doc/paddle/api/paddle/distributed/broadcast_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..33e653b56648ff6f97b64b19fffcf64bca4a989c --- /dev/null +++ b/doc/paddle/api/paddle/distributed/broadcast_cn.rst @@ -0,0 +1,39 @@ +.. _cn_api_distributed_broadcast: + +broadcast +------------------------------- + + +.. py:function:: paddle.distributed.broadcast(tensor, src, group=0) + +广播一个Tensor给其他所有进程 + +参数 +::::::::: + - tensor (Tensor) - 如果当前进程编号是源，那么这个Tensor变量将被发送给其他进程，否则这个Tensor将接收源发送过来的数据。Tensor的数据类型为：float16、float32、float64、int32、int64。 + - src (int) - 发送源的进程编号。 + - group (int，可选) - 工作的进程组编号，默认为0。 + +返回 +::::::::: +无 + +代码示例 +::::::::: +.. code-block:: python + + import numpy as np + import paddle + from paddle.distributed import init_parallel_env + + paddle.disable_static() + paddle.set_device('gpu:%d'%paddle.distributed.ParallelEnv().dev_id) + init_parallel_env() + if paddle.distributed.ParallelEnv().local_rank == 0: + np_data = np.array([[4, 5, 6], [4, 5, 6]]) + else: + np_data = np.array([[1, 2, 3], [1, 2, 3]]) + data = paddle.to_tensor(np_data) + paddle.distributed.broadcast(data, 1) + out = data.numpy() + # [[1, 2, 3], [1, 2, 3]] diff --git a/doc/paddle/api/paddle/distributed/fleet/InMemoryDataset_cn.rst b/doc/paddle/api/paddle/distributed/fleet/InMemoryDataset_cn.rst deleted file mode 100644 index 7699284c681fd87008d3b8ad41db89a93fd8d788..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/distributed/fleet/InMemoryDataset_cn.rst +++ /dev/null @@ -1,357 +0,0 @@ -.. _cn_api_fluid_dataset_InMemoryDataset: - -InMemoryDataset -------------------------------- - -.. py:class:: paddle.fluid.dataset.InMemoryDataset - - - - -InMemoryDataset会向内存中加载数据并在训练前缓冲数据。此类由DatasetFactory创建。 - -**代码示例**: - -.. code-block:: python - - dataset = paddle.fluid.DatasetFactory().create_dataset(“InMemoryDataset”) - -.. py:method:: set_queue_num(queue_num) - -设置 ``Dataset`` 输出队列数量，训练进程会从队列中获取数据。 - -参数： - - **queue_num** (int) - dataset输出队列数量 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - dataset.set_queue_num(12) - -.. py:method:: set_fleet_send_batch_size(fleet_send_batch_size) - -设置发送batch的大小 - -参数: - - **fleet_send_batch_size** (int) - 设置发送batch的大小。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - dataset.set_fleet_send_batch_size(800) - -.. py:method:: set_merge_by_lineid(var_list, erase_duplicate_feas=True, min_merge_size=2, keep_unmerged-ins=True) - -通过样本id来设置合并，一些线id的实例将会在shuffle之后进行合并，你应该在一个data生成器里面解析样本id。 - -参数: - - **var_list** (list) - 可以被合并的特征列表，其中的每一个元素都是一个 ``Variable`` 。一些类特征我们通常不把它们合并为同样的样本id，所以用户应当指定哪个类特征可以被合并。 - - **erase_duplicate_feas** (bool) - 合并的时候是否删除重复的特征值。默认为True。 - - **min_merge_size** (int) - 合并的最小数量。默认为2。 - - **keep_unmerged_ins** (bool) - 是否保留没有合并的样本，比如有着独特id的样本，或者重复id的数量小于 ``min_merge_size`` 的样本。 - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - dataset.set_merge_by_lineid() - -.. py:method:: load_into_memory() - -向内存中加载数据。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.load_into_memory() - -.. py:method:: preload_into_memory() - -向内存中以异步模式加载数据。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.preload_into_memory() - dataset.wait_preload_done() - -.. py:method:: wait_preload_done() - -等待 ``preload_into_memory`` 完成。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.preload_into_memory() - dataset.wait_preload_done() - -.. py:method:: local_shuffle() - -局域shuffle。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.load_into_memory() - dataset.local_shuffle() - - -.. py:method:: global_shuffle(fleet=None) - -全局shuffle。 - -只能用在分布式模式（单机多进程或多机多进程）中。您如果在分布式模式中运行，应当传递fleet而非None。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.load_into_memory() - dataset.global_shuffle(fleet) - -参数： - - **fleet** (Fleet) – fleet单例。默认为None。 - - -.. py:method:: release_memory() - -当数据不再使用时，释放InMemoryDataset内存数据。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.load_into_memory() - dataset.global_shuffle(fleet) - exe = fluid.Executor(fluid.CPUPlace()) - exe.run(fluid.default_startup_program()) - exe.train_from_dataset(fluid.default_main_program(), dataset) - dataset.release_memory() - -.. py:method:: get_memory_data_size(fleet=None) - -用户可以调用此函数以了解加载进内存后所有workers中的样本数量。 - -.. note:: - 该函数可能会导致性能不佳，因为它具有barrier。 - -参数： - - **fleet** (Fleet) – fleet对象。 - -返回：内存数据的大小。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.load_into_memory() - print dataset.get_memory_data_size(fleet) - - -.. py:method:: get_shuffle_data_size(fleet=None) - -获取shuffle数据大小，用户可以调用此函数以了解局域/全局shuffle后所有workers中的样本数量。 - -.. note:: - 该函数可能会导致局域shuffle性能不佳，因为它具有barrier。但其不影响局域shuffle。 - -参数： - - **fleet** (Fleet) – fleet对象。 - -返回：shuffle数据的大小。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet - dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset") - filelist = ["a.txt", "b.txt"] - dataset.set_filelist(filelist) - dataset.load_into_memory() - dataset.global_shuffle(fleet) - print dataset.get_shuffle_data_size(fleet) - - -.. py:method:: set_batch_size(batch_size) - -设置batch size。在训练期间生效。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_batch_size(128) - -参数： - - **batch_size** (int) - batch size - -.. py:method:: set_fea_eval(record_candidate_size, fea_eval=True) - -设置特征打乱特征验证模式，来修正特征level的重要性， 特征打乱需要 ``fea_eval`` 被设置为True。 - -参数： - - **record_candidate_size** (int) - 打乱一个特征的候选实例大小 - - **fea_eval** (bool) - 是否设置特征验证模式来打乱特征，默认为True。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset(“InMemoryDataset”) - dataset.set_fea_eval(1000000, True) - -.. py:method:: desc() - -为 ``DataFeedDesc`` 返回一个缓存信息。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - print(dataset.desc()) - -返回：一个字符串信息 - -.. py:method:: set_filelist(filelist) - -在当前的worker中设置文件列表。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_filelist(["a.txt", "b.txt"]) - -参数： - - **filelist** (list) - 文件列表 - -.. py:method:: set_hdfs_config(fs_name, fs_ugi) - -设置hdfs配置：fs名称与ugi。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_hdfs_config("my_fs_name", "my_fs_ugi") - -参数： - - **fs_name** (str) - fs名称 - - **fs_ugi** (str) - fs ugi - -.. py:method:: set_pipe_command(pipe_coommand) - -在当前的 ``dataset`` 中设置pipe命令。pipe命令只能使用UNIX的pipe命令 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_pipe_command("python my_script.py") - -参数： - - **pipe_command** (str) - pipe命令 - -.. py:method:: set_thread(thread_num) - -设置进程数量，等于readers的数量。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_thread(12) - -参数： - - **thread_num** (int) - 进程数量 - -.. py:method:: set_use_var(var_list) - -设置将要使用的 ``Variable`` 。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_use_var([data, label]) - -参数： - - **var_list** (list) - variable 列表 - -.. py:method:: slots_shuffle(slots) - -该方法是在特征层次上的一个打乱方法，经常被用在有着较大缩放率实例的稀疏矩阵上，为了比较metric，比如auc，在一个或者多个有着baseline的特征上做特征打乱来验证特征level的重要性。 - -参数： - - **slots** (list[string]) - 要打乱特征的集合 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset(“InMemoryDataset”) - dataset.set_merge_by_lineid() - #支持slot 0 - dataset.slots_shuffle([‘0’]) - - - diff --git a/doc/paddle/api/paddle/distributed/fleet/QueueDataset_cn.rst b/doc/paddle/api/paddle/distributed/fleet/QueueDataset_cn.rst deleted file mode 100644 index 298bf2bb4ecc8b356327af82570e7bb07e2e2907..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/distributed/fleet/QueueDataset_cn.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. _cn_api_fluid_dataset_QueueDataset: - -QueueDataset -------------------------------- - -.. py:class:: paddle.fluid.dataset.QueueDataset - - - - -流式处理数据。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("QueueDataset") - - - -.. py:method:: local_shuffle() - -局域shuffle数据 - -QueueDataset中不支持局域shuffle，可能抛出NotImplementedError - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset("QueueDataset") - dataset.local_shuffle() - - - -.. py:method:: global_shuffle(fleet=None) - -全局shuffle数据 - -QueueDataset中不支持全局shuffle，可能抛出NotImplementedError - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet - dataset = fluid.DatasetFactory().create_dataset("QueueDataset") - dataset.global_shuffle(fleet) - -.. py:method:: desc() - -为 ``DataFeedDesc`` 返回一个缓存信息。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - print(dataset.desc()) - -返回：一个字符串信息 - -.. py:method:: set_batch_size(batch_size) - -设置batch size。在训练期间生效。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_batch_size(128) - -参数： - - **batch_size** (int) - batch size - -.. py:method:: set_fea_eval(record_candidate_size,fea_eval) - -参数： - - **record_candidate_size** (int) - 打乱一个特征的候选实例大小 - - **fea_eval** (bool) - 是否设置特征验证模式来打乱特征，默认为True。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset(“InMemoryDataset”) - dataset.set_fea_eval(1000000, True) - -.. py:method:: set_filelist(filelist) - -在当前的worker中设置文件列表。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_filelist(["a.txt", "b.txt"]) - -参数： - - **filelist** (list) - 文件列表 - -.. py:method:: set_hdfs_config(fs_name, fs_ugi) - -设置hdfs配置：fs名称与ugi。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_hdfs_config("my_fs_name", "my_fs_ugi") - -参数： - - **fs_name** (str) - fs名称 - - **fs_ugi** (str) - fs ugi - -.. py:method:: set_pipe_command(pipe_coommand) - -在当前的 ``dataset`` 中设置pipe命令。pipe命令只能使用UNIX的pipe命令 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_pipe_command("python my_script.py") - -参数： - - **pipe_command** (str) - pipe命令 - -.. py:method:: set_thread(thread_num) - -设置进程数量，等于readers的数量。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_thread(12) - -参数： - - **thread_num** (int) - 进程数量 - -.. py:method:: set_use_var(var_list) - -设置将要使用的 ``Variable`` 。 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset() - dataset.set_use_var([data, label]) - -参数： - - **var_list** (list) - variable 列表 - -.. py:method:: slots_shuffle(slots) - -该方法是在特征层次上的一个打乱方法，经常被用在有着较大缩放率实例的稀疏矩阵上，为了比较metric，比如auc，在一个或者多个有着baseline的特征上做特征打乱来验证特征level的重要性。 - -参数： - - **slots** (list[string]) - 要打乱特征的集合 - -**代码示例**: - -.. code-block:: python - - import paddle.fluid as fluid - dataset = fluid.DatasetFactory().create_dataset(“InMemoryDataset”) - dataset.set_merge_by_lineid() - #支持slot 0 - dataset.slots_shuffle([‘0’]) - diff --git a/doc/paddle/api/paddle/distributed/fleet/meta_optimizers/LambOptimizer_cn.rst b/doc/paddle/api/paddle/distributed/fleet/meta_optimizers/LambOptimizer_cn.rst deleted file mode 100644 index 0be07027ecd6260fc691b11ee1cb38fbf72ba143..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/distributed/fleet/meta_optimizers/LambOptimizer_cn.rst +++ /dev/null @@ -1,226 +0,0 @@ -.. _cn_api_fluid_optimizer_LambOptimizer: - -LambOptimizer -------------------------------- - -.. py:class:: paddle.fluid.optimizer.LambOptimizer(learning_rate=0.001, lamb_weight_decay=0.01, beta1=0.9, beta2=0.999, epsilon=1e-06, parameter_list=None, regularization=None, grad_clip=None, exclude_from_weight_decay_fn=None, name=None) - - - - -LAMB（Layer-wise Adaptive Moments optimizer for Batching training）优化器 -LAMB的优化器旨在不降低精度的前提下增大训练的批量大小，其支持自适应的逐元素更新和精确的分层校正。 更多信息请参考 `Large Batch Optimization for -Deep Learning: Training BERT in 76 minutes `_ 。 -参数更新如下： - -.. math:: - - \begin{align} - \begin{aligned} - m_t &= \beta_1 m_{t - 1}+ (1 - \beta_1)g_t \\ - v_t &= \beta_2 v_{t - 1} + (1 - \beta_2)g_t^2 \\ - r_t &= \frac{m_t}{\sqrt{v_t}+\epsilon} \\ - w_t &= w_{t-1} -\eta_t \frac{\left \| w_{t-1}\right \|}{\left \| r_t + \lambda w_{t-1}\right \|} (r_t + \lambda w_{t-1}) - \end{aligned} - \end{align} - -其中 :math:`m` 为第一个动量，:math:`v` 为第二个动量，:math:`\eta` 为学习率，:math:`\lambda` 为 LAMB 权重衰减率。 - -参数： - - **learning_rate** (float|Variable) – 用于更新参数的学习率。可以是浮点数，或数据类型为浮点数的 Variable。 - - **lamb_weight_decay** (float) – LAMB权重衰减率。 - - **beta1** (float) – 第一个动量估计的指数衰减率。 - - **beta2** (float) – 第二个动量估计的指数衰减率。 - - **epsilon** (float) – 一个小的浮点值，目的是维持数值稳定性。 - - **parameter_list** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 - - **regularization** (WeightDecayRegularizer，可选) - 正则化方法。支持两种正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 - :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； - 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 - - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 - 默认值为None，此时将不进行梯度裁剪。 - - **exclude_from_weight_decay_fn** (function) – 当某个参数作为输入该函数返回值为 ``True`` 时，为该参数跳过权重衰减。 - - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - data = fluid.layers.data(name='x', shape=[5], dtype='float32') - hidden = fluid.layers.fc(input=data, size=10) - cost = fluid.layers.mean(hidden) - - def exclude_fn(param): - return param.name.endswith('.b_0') - - optimizer = fluid.optimizer.Lamb(learning_rate=0.002, - exclude_from_weight_decay_fn=exclude_fn) - optimizer.minimize(cost) - - -.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None) - -为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameter_list中的Parameters，最小化网络损失值loss。 - -参数： - - **loss** (Variable) – 需要最小化的损失值变量。 - - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` - - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter - - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的的集合，默认值为None - -返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 - -返回类型： tuple - -**代码示例**： - -.. code-block:: python - - import numpy - import paddle.fluid as fluid - - x = fluid.layers.data(name='X', shape=[13], dtype='float32') - y = fluid.layers.data(name='Y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - loss = fluid.layers.mean(cost) - adam = fluid.optimizer.LambOptimizer(learning_rate=0.2) - adam.minimize(loss) - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - - x = numpy.random.random(size=(10, 13)).astype('float32') - y = numpy.random.random(size=(10, 1)).astype('float32') - exe.run(fluid.default_startup_program()) - outs = exe.run(program=fluid.default_main_program(), - feed={'X': x, 'Y': y}, - fetch_list=[loss.name]) - - - -.. py:method:: clear_gradients() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - - -清除需要优化的参数的梯度。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - def exclude_fn(param): - return param.name.endswith('.b_0') - - with fluid.dygraph.guard(): - value = np.arange(26).reshape(2, 13).astype("float32") - a = fluid.dygraph.to_variable(value) - linear = fluid.Linear(13, 5, dtype="float32") - optimizer = fluid.optimizer.LambOptimizer(learning_rate=0.02, - exclude_from_weight_decay_fn=exclude_fn, - parameter_list=linear.parameters()) - out = linear(a) - out.backward() - optimizer.minimize(out) - optimizer.clear_gradients() - -.. py:method:: set_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -手动设置当前 ``optimizer`` 的学习率。当使用LearningRateDecay时，无法使用该API手动设置学习率，因为这将导致冲突。 - -参数： - value (float|Variable) - 需要设置的学习率的值。 - -返回：无 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - linear = fluid.dygraph.nn.Linear(10, 10) - adam = fluid.optimizer.Adam(0.1, parameter_list=linear.parameters()) - # 通过Python float数值手动设置学习率 - lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] - for i in range(5): - adam.set_lr(lr_list[i]) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.2 - # current lr is 0.3 - # current lr is 0.4 - # current lr is 0.5 - # current lr is 0.6 - - - # 通过 框架的Variable 设置学习率 - lr_var = fluid.layers.create_global_var(shape=[1], value=0.7, dtype='float32') - adam.set_lr(lr_var) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.7 - - - -.. py:method:: current_step_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -获取当前步骤的学习率。当不使用LearningRateDecay时，每次调用的返回值都相同，否则返回当前步骤的学习率。 - -返回：当前步骤的学习率。 - -返回类型：float - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # example1: LearningRateDecay is not used, return value is all the same - with fluid.dygraph.guard(): - emb = fluid.dygraph.Embedding([10, 10]) - adam = fluid.optimizer.Adam(0.001, parameter_list = emb.parameters()) - lr = adam.current_step_lr() - print(lr) # 0.001 - - # example2: PiecewiseDecay is used, return the step learning rate - with fluid.dygraph.guard(): - inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") - linear = fluid.dygraph.nn.Linear(10, 10) - inp = fluid.dygraph.to_variable(inp) - out = linear(inp) - loss = fluid.layers.reduce_mean(out) - - bd = [2, 4, 6, 8] - value = [0.2, 0.4, 0.6, 0.8, 1.0] - adam = fluid.optimizer.Adam(fluid.dygraph.PiecewiseDecay(bd, value, 0), - parameter_list=linear.parameters()) - - # first step: learning rate is 0.2 - np.allclose(adam.current_step_lr(), 0.2, rtol=1e-06, atol=0.0) # True - - # learning rate for different steps - ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] - for i in range(12): - adam.minimize(loss) - lr = adam.current_step_lr() - np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True - diff --git a/doc/paddle/api/paddle/distributed/fleet/meta_optimizers/RecomputeOptimizer_cn.rst b/doc/paddle/api/paddle/distributed/fleet/meta_optimizers/RecomputeOptimizer_cn.rst deleted file mode 100644 index d521b74471a50245f85085500ca9f716e9ba5d62..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/distributed/fleet/meta_optimizers/RecomputeOptimizer_cn.rst +++ /dev/null @@ -1,196 +0,0 @@ -.. _cn_api_fluid_optimizer_RecomputeOptimizer: - -RecomputeOptimizer -------------------------------- - - -.. py:class:: paddle.fluid.optimizer.RecomputeOptimizer(optimizer) - -:api_attr: 声明式编程模式（静态图) - - - -通常来讲，一个深度学习的训练流程包含了三个子步骤：首先，运行前向算子来计算Variable和loss的值；其次，运行反向算子来计算参数的梯度；最后，应用优化算法以更新参数值。 - -在前向运算过程中，反向运算会用到的Variable都会保存在内存中，当模型深度很深时，这会占用大量的内存。 - -重计算将深度学习网络切分为k个部分（segments）。在每个segment，运行反向运算时会首先运算前向计算。在重计算模式下，前向计算除了checkpoint和一些必须存储在内存中的特殊Variable，其他临时Variable都会被释放，这对节省内存非常有益。 - -把一个深度学习网络切分为k个segments的Variables被称为checkpoints。用户在使用运行RecomputeOptimizer之前需要先设置checkpoints。 - -参数: - - **optimizer** (Optimizer)-内部优化器 - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - def gen_data(): - return {"x": np.random.random(size=(32, 32)).astype('float32'), - "y": np.random.randint(2, size=(32, 1)).astype('int64')} - def mlp(input_x, input_y, hid_dim=128, label_dim=2): - print(input_x) - fc_1 = fluid.layers.fc(input=input_x, size=hid_dim) - prediction = fluid.layers.fc(input=[fc_1], size=label_dim, act='softmax') - cost = fluid.layers.cross_entropy(input=prediction, label=input_y) - sum_cost = fluid.layers.reduce_mean(cost) - return sum_cost, fc_1, prediction - input_x = fluid.layers.data(name="x", shape=[32], dtype='float32') - input_y = fluid.layers.data(name="y", shape=[1], dtype='int64') - cost, fc_1, pred = mlp(input_x, input_y) - - sgd = fluid.optimizer.Adam(learning_rate=0.01) - sgd = fluid.optimizer.RecomputeOptimizer(sgd) - sgd._set_checkpoints([fc_1, pred]) - sgd.minimize(cost) - - print("Finished optimize") - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - step = 10 - - for i in range(step): - cost_val = exe.run(feed=gen_data(), - program=fluid.default_main_program(), - fetch_list=[cost.name]) - print("step=%d cost=%f" % (i, cost_val[0])) - - -.. py:method:: apply_gradients(params_grads) - -调用self.apply_gradients - -参数： - - **params_grads** (list)- 用于优化的(param, grad)对组成的列表 - -返回： 附加在当前Program的优化算子组成的列表 - -返回类型： list - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import paddle.fluid.framework as framework - - def mlp(input_x, input_y, hid_dim=128, label_dim=2): - fc_1 = fluid.layers.fc(input=input_x, size=hid_dim) - prediction = fluid.layers.fc(input=[fc_1], size=label_dim, act='softmax') - cost = fluid.layers.cross_entropy(input=prediction, label=input_y) - sum_cost = fluid.layers.reduce_mean(cost) - return sum_cost, fc_1, prediction - - - input_x = fluid.layers.data(name="x", shape=[32], dtype='float32') - input_y = fluid.layers.data(name="y", shape=[1], dtype='int64') - cost, fc_1, pred = mlp(input_x, input_y) - print("Finished FF") - - sgd = fluid.optimizer.Adam(learning_rate=0.01) - sgd = fluid.optimizer.RecomputeOptimizer(sgd) - params_grads = sgd.backward( - cost, - startup_program=None, - parameter_list=None, - no_grad_set=None) - - program = cost.block.program - with framework.program_guard(program, None): - optimize_ops = sgd.apply_gradients(params_grads) - - print("Finished apply gradients") - -.. py:method:: apply_optimize(loss, startup_program, params_grads) - -调用self._optimizer的apply_optimize函数 - -参数： - - **loss** (Variable) – 用于优化过程的损失值变量 - - **startup_program** (Program) – 用于初始化在parameter_list中参数的startup_program - - **params_grads** (list)- 用于优化的(param, grad)对组成的列表 - -返回： 附加在当前Program的算子组成的列表 - -返回类型： list - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - def mlp(input_x, input_y, hid_dim=128, label_dim=2): - fc_1 = fluid.layers.fc(input=input_x, size=hid_dim) - prediction = fluid.layers.fc(input=[fc_1], size=label_dim, act='softmax') - cost = fluid.layers.cross_entropy(input=prediction, label=input_y) - sum_cost = fluid.layers.reduce_mean(cost) - return sum_cost, fc_1, prediction - - input_x = fluid.layers.data(name="x", shape=[32], dtype='float32') - input_y = fluid.layers.data(name="y", shape=[1], dtype='int64') - cost, fc_1, pred = mlp(input_x, input_y) - print("Finished FF") - - sgd = fluid.optimizer.Adam(learning_rate=0.01) - sgd = fluid.optimizer.RecomputeOptimizer(sgd) - params_grads = sgd.backward( - cost, - startup_program=None, - parameter_list=None, - no_grad_set=None) - - optimize_ops = sgd.apply_optimize( - cost, startup_program=None, params_grads=params_grads) - - print("Finished apply_optimize") - -.. py:method:: backward(loss, startup_program=None, parameter_list=None, no_grad_set=None, callbacks=None) - -带checkpoint的backward函数 - -参数： - - **loss** (Variable) – 需要最小化的损失值变量 - - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` - - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter - - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的的集合，默认值为None - - **callbacks** (list, 可选) – 当为某参数附加反向算子时所要运行的callables组成的列表 - - **checkpoints** (list, 可选) – 一批作为checkpoints的Variables - -返回： 由(param, grad)对构成的列表，其中param是参数，grad是其对应的梯度 - -返回类型： list - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - def mlp(input_x, input_y, hid_dim=128, label_dim=2): - fc_1 = fluid.layers.fc(input=input_x, size=hid_dim) - prediction = fluid.layers.fc(input=[fc_1], size=label_dim, act='softmax') - cost = fluid.layers.cross_entropy(input=prediction, label=input_y) - sum_cost = fluid.layers.reduce_mean(cost) - return sum_cost, fc_1, prediction - - - input_x = fluid.layers.data(name="x", shape=[32], dtype='float32') - input_y = fluid.layers.data(name="y", shape=[1], dtype='int64') - cost, fc_1, pred = mlp(input_x, input_y) - print("Finished FF") - - sgd = fluid.optimizer.Adam(learning_rate=0.01) - sgd = fluid.optimizer.RecomputeOptimizer(sgd) - params_grads = sgd.backward( - cost, - startup_program=None, - parameter_list=None, - no_grad_set=None) - print("Finished backward") - - - diff --git a/doc/paddle/api/paddle/distributed/get_rank_cn.rst b/doc/paddle/api/paddle/distributed/get_rank_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..75ad8fc79baa6a560fe956799c1a00bc9d67376d --- /dev/null +++ b/doc/paddle/api/paddle/distributed/get_rank_cn.rst @@ -0,0 +1,25 @@ +.. _cn_api_distributed_get_rank: + +get_rank +---------- + +.. py:function:: paddle.distributed.get_rank() + +返回当前进程的rank。 + +当前进程rank的值等于环境变量 ``PADDLE_TRAINER_ID`` 的值，默认值为0。 + +返回 +::::::::: +(int) 当前进程的rank。 + +代码示例 +::::::::: +.. code-block:: python + + import paddle + import paddle.distributed as dist + + # execute this command in terminal: export PADDLE_TRAINER_ID=0 + print("The rank is %d" % dist.get_rank()) + # The rank is 0 diff --git a/doc/paddle/api/paddle/distributed/get_world_size_cn.rst b/doc/paddle/api/paddle/distributed/get_world_size_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..08342de3c1f44b96762eefb1d9ae96918112d9dd --- /dev/null +++ b/doc/paddle/api/paddle/distributed/get_world_size_cn.rst @@ -0,0 +1,25 @@ +.. _cn_api_distributed_get_world_size: + +get_world_size +---------------- + +.. py:function:: paddle.distributed.get_world_size() + +返回参与当前任务的进程数。 + +当前进程数等于环境变量 ``PADDLE_TRAINERS_NUM`` 的值，默认值为1。 + +返回 +::::::::: +(int) 参与任务的进程数。 + +代码示例 +::::::::: +.. code-block:: python + + import paddle + import paddle.distributed as dist + + # execute this command in terminal: export PADDLE_TRAINERS_NUM=4 + print("The world_size is %d" % dist.get_world_size()) + # The world_size is 4 diff --git a/doc/paddle/api/paddle/distributed/init_parallel_env_cn.rst b/doc/paddle/api/paddle/distributed/init_parallel_env_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..eafe9f10f0548931828798b28896ef59f211eefe --- /dev/null +++ b/doc/paddle/api/paddle/distributed/init_parallel_env_cn.rst @@ -0,0 +1,64 @@ +.. _cn_api_distributed_init_parallel_env: + +init_parallel_env +----------------- + +.. py:function:: paddle.distributed.init_parallel_env() + +初始化动态图模式下的并行训练环境。 + +.. note:: + 目前仅支持初始化GPU训练环境，使用NCCL进行通信。 + +返回 +::::::::: +无 + +代码示例 +::::::::: +.. code-block:: python + + import paddle + import paddle.nn as nn + import paddle.optimizer as opt + import paddle.distributed as dist + + class LinearNet(nn.Layer): + def __init__(self): + super(LinearNet, self).__init__() + self._linear1 = nn.Linear(10, 10) + self._linear2 = nn.Linear(10, 1) + + def forward(self, x): + return self._linear2(self._linear1(x)) + + def train(): + # 1. enable dynamic mode + paddle.disable_static() + + # 2. initialize parallel environment + dist.init_parallel_env() + + # 3. create data parallel layer & optimizer + layer = LinearNet() + dp_layer = paddle.DataParallel(layer) + + loss_fn = nn.MSELoss() + adam = opt.Adam( + learning_rate=0.001, parameters=dp_layer.parameters()) + + # 4. run layer + inputs = paddle.randn([10, 10], 'float32') + outputs = dp_layer(inputs) + labels = paddle.randn([10, 1], 'float32') + loss = loss_fn(outputs, labels) + + loss = dp_layer.scale_loss(loss) + loss.backward() + dp_layer.apply_collective_grads() + + adam.step() + adam.clear_grad() + + if __name__ == '__main__': + dist.spawn(train) diff --git a/doc/paddle/api/paddle/fluid/dygraph/parallel/prepare_context_cn.rst b/doc/paddle/api/paddle/distributed/prepare_context_cn.rst similarity index 100% rename from doc/paddle/api/paddle/fluid/dygraph/parallel/prepare_context_cn.rst rename to doc/paddle/api/paddle/distributed/prepare_context_cn.rst diff --git a/doc/paddle/api/paddle/distributed/reduce_cn.rst b/doc/paddle/api/paddle/distributed/reduce_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..6f471a67a8a0a17617f18208ca9b596ce8182f5e --- /dev/null +++ b/doc/paddle/api/paddle/distributed/reduce_cn.rst @@ -0,0 +1,40 @@ +.. _cn_api_distributed_reduce: + +reduce +------------------------------- + + +.. py:function:: paddle.distributed.reduce(tensor, dst, op=ReduceOp.SUM, group=0) + +进程组内所有进程的指定tensor进行归约操作，并返回给所有进程归约的结果。 + +参数 +::::::::: + - tensor (Tensor) - 操作的输入Tensor，结果返回至目标进程号的Tensor中。Tensor的数据类型为：float16、float32、float64、int32、int64。 + - dst (int) - 返回操作结果的目标进程编号。 + - op (ReduceOp.SUM|ReduceOp.MAX|ReduceOp.Min|ReduceOp.PROD，可选) - 归约的具体操作，比如求和，取最大值，取最小值和求乘积，默认为求和归约。 + - group (int，可选) - 工作的进程组编号，默认为0。 + +返回 +::::::::: +无 + +代码示例 +::::::::: +.. code-block:: python + + import numpy as np + import paddle + from paddle.distributed import init_parallel_env + + paddle.disable_static() + paddle.set_device('gpu:%d'%paddle.distributed.ParallelEnv().dev_id) + init_parallel_env() + if paddle.distributed.ParallelEnv().local_rank == 0: + np_data = np.array([[4, 5, 6], [4, 5, 6]]) + else: + np_data = np.array([[1, 2, 3], [1, 2, 3]]) + data = paddle.to_tensor(np_data) + paddle.distributed.reduce(data, 0) + out = data.numpy() + # [[5, 7, 9], [5, 7, 9]] diff --git a/doc/paddle/api/paddle/distributed/scatter_cn.rst b/doc/paddle/api/paddle/distributed/scatter_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..43a9aad6d7d9f4d06a6cd3f544ed13af6428c1bd --- /dev/null +++ b/doc/paddle/api/paddle/distributed/scatter_cn.rst @@ -0,0 +1,78 @@ +.. _cn_api_paddle_cn_scatter: + +scatter +------------------------------- +.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None) + + +通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下： + + .. code-block:: python + + import numpy as np + #input: + x = np.array([[1, 1], [2, 2], [3, 3]]) + index = np.array([2, 1, 0, 1]) + # shape of updates should be the same as x + # shape of updates with dim > 1 should be the same as input + updates = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]) + overwrite = False + # calculation: + if not overwrite: + for i in range(len(index)): + x[index[i]] = np.zeros((2)) + for i in range(len(index)): + if (overwrite): + x[index[i]] = updates[i] + else: + x[index[i]] += updates[i] + # output: + out = np.array([[3, 3], [6, 6], [1, 1]]) + out.shape # [3, 2] + +**Notice：** +因为 ``updates`` 的应用顺序是不确定的，因此，如果索引 ``index`` 包含重复项，则输出将具有不确定性。 + + +参数： + - **x** (Tensor) - ndim> = 1的输入N-D张量。 数据类型可以是float32，float64。 + - **index** （Tensor）- 一维Tensor。 数据类型可以是int32，int64。 ``index`` 的长度不能超过 ``updates`` 的长度，并且 ``index`` 中的值不能超过输入的长度。 + - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x`` 。 形状应与输入 ``x`` 相同，并且dim>1的dim值应与输入 ``x`` 相同。 + - **overwrite** （bool，可选）- 指定索引 ``index`` 相同时，更新输出的方式。如果为True，则使用覆盖模式更新相同索引的输出，如果为False，则使用累加模式更新相同索引的输出。默认值为True。 + - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：Tensor，与x有相同形状和数据类型。 + + +**代码示例：** + .. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + x_data = np.array([[1, 1], [2, 2], [3, 3]]).astype(np.float32) + index_data = np.array([2, 1, 0, 1]).astype(np.int64) + updates_data = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]).astype(np.float32) + + x = paddle.to_tensor(x_data) + index = paddle.to_tensor(index_data) + updates = paddle.to_tensor(updates_data) + + output1 = paddle.scatter(x, index, updates, overwrite=False) + # [[3., 3.], + # [6., 6.], + # [1., 1.]] + output2 = paddle.scatter(x, index, updates, overwrite=True) + # CPU device: + # [[3., 3.], + # [4., 4.], + # [1., 1.]] + # GPU device maybe have two results because of the repeated numbers in index + # result 1: + # [[3., 3.], + # [4., 4.], + # [1., 1.]] + # result 2: + # [[3., 3.], + # [2., 2.], + # [1., 1.]] diff --git a/doc/paddle/api/paddle/distributed/spawn_cn.rst b/doc/paddle/api/paddle/distributed/spawn_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..21f8f762f5052474aac91c31ada8f76b664594b2 --- /dev/null +++ b/doc/paddle/api/paddle/distributed/spawn_cn.rst @@ -0,0 +1,105 @@ +.. _cn_api_distributed_spawn: + +spawn +----- + +.. py:function:: paddle.distributed.spawn(func, args=(), nprocs=-1, join=True, daemon=False, **options) + +使用 ``spawn`` 方法启动多进程任务。 + +参数 +::::::::: + - func (function) - 由 ``spawn`` 方法启动的进程所调用的目标函数。该目标函数需要能够被 ``pickled`` (序列化)，所以目标函数必须定义为模块的一级函数，不能是内部子函数或者类方法。 + - args (tuple, 可选) - 传入目标函数 ``func`` 的参数。 + - nprocs (int, 可选) - 启动进程的数目。默认值为-1。当 ``nproc`` 为-1时，模型执行时将会从环境变量中获取当前可用的所有设备进行使用：如果使用GPU执行任务，将会从环境变量 ``CUDA_VISIBLE_DEVICES`` 中获取当前所有可用的设备ID；如果使用CPU执行任务，将会从环境变量 ``CPU_NUM`` 中获取当前可用的CPU设备数，例如，可以通过指令 ``export CPU_NUM=4`` 配置默认可用CPU设备数，如果此环境变量没有设置，将会默认设置该环境变量的值为1。 + - join (bool, 可选) - 对所有启动的进程执行阻塞的 ``join`` ，等待进程执行结束。默认为True。 + - daemon (bool, 可选) - 配置启动进程的 ``daemon`` 属性。默认为False。 + - **options (dict, 可选) - 其他初始化并行执行环境的配置选项。目前支持以下选项： (1) start_method (string) - 启动子进程的方法。进程的启动方法可以是 ``spawn`` ， ``fork`` , ``forkserver`` 。 因为CUDA运行时环境不支持 ``fork`` 方法，当在子进程中使用CUDA时，需要使用 ``spawn`` 或者 ``forkserver`` 方法启动进程。默认方法为 ``spawn`` ； (2) cluster_node_ips (string) - 运行集群的节点（机器）IP，例如 "192.168.0.16,192.168.0.17" ，默认值为 "127.0.0.1" ； (3) node_ip (string) - 当前节点（机器）的IP。例如 "192.168.0.16" , 默认值为 "127.0.0.1" ； (4) started_port (int) - 一个训练节点（机器）上各训练进程的起始端口。例如 6170. 默认值为None ； (5) selected_gpus (string) - 指定训练使用的GPU ID, 例如 "0,1,2,3" ， 默认值为None ； (6) print_config (bool) - 打印当前并行训练的配置， 默认值为False ； (7) use_paddlecloud (bool) - 配置是否使用PaddleCloud启动多进程任务，默认值为False。 + +返回 +::::::::: + ``MultiprocessContext`` 对象，持有创建的多个进程。 + +代码示例 +::::::::: +.. code-block:: python + + from __future__ import print_function + + import paddle + import paddle.nn as nn + import paddle.optimizer as opt + import paddle.distributed as dist + + class LinearNet(nn.Layer): + def __init__(self): + super(LinearNet, self).__init__() + self._linear1 = nn.Linear(10, 10) + self._linear2 = nn.Linear(10, 1) + + def forward(self, x): + return self._linear2(self._linear1(x)) + + def train(print_result=False): + # 1. enable dynamic mode + paddle.disable_static() + + # 2. initialize parallel environment + dist.init_parallel_env() + + # 3. create data parallel layer & optimizer + layer = LinearNet() + dp_layer = paddle.DataParallel(layer) + + loss_fn = nn.MSELoss() + adam = opt.Adam( + learning_rate=0.001, parameters=dp_layer.parameters()) + + # 4. run layer + inputs = paddle.randn([10, 10], 'float32') + outputs = dp_layer(inputs) + labels = paddle.randn([10, 1], 'float32') + loss = loss_fn(outputs, labels) + + if print_result is True: + print("loss:", loss.numpy()) + + loss = dp_layer.scale_loss(loss) + loss.backward() + dp_layer.apply_collective_grads() + + adam.step() + adam.clear_grad() + + # Usage 1: only pass function. + # If your training method no need any argument, and + # use all visible devices for parallel training. + if __name__ == '__main__': + dist.spawn(train) + + # Usage 2: pass function and arguments. + # If your training method need some arguments, and + # use all visible devices for parallel training. + if __name__ == '__main__': + dist.spawn(train, args=(True,)) + + # Usage 3: pass function, arguments and nprocs. + # If your training method need some arguments, and + # only use part of visible devices for parallel training. + # If your machine hold 8 cards {0,1,2,3,4,5,6,7}, + # this case will use cards {0,1}; If you set + # CUDA_VISIBLE_DEVICES=4,5,6,7, this case will use + # cards {4,5} + if __name__ == '__main__': + dist.spawn(train, args=(True,), nprocs=2) + + # Usage 4: pass function, arguments, nprocs and selected_gpus. + # If your training method need some arguments, and + # only use part of visible devices for parallel training, + # but you can't set your machine's environment varibale + # CUDA_VISIBLE_DEVICES, such as it is None or all cards + # {0,1,2,3,4,5,6,7}, you can pass `selelcted_gpus` to + # select the GPU cards you want to use. For example, + # this case will use cards {4,5} if your machine hold 8 cards. + if __name__ == '__main__': + dist.spawn(train, args=(True,), nprocs=2, selelcted_gpus='4,5') \ No newline at end of file diff --git a/doc/paddle/api/paddle/distribution/Distribution_cn.rst b/doc/paddle/api/paddle/distribution/Distribution_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c513c281df548f83a62a5183a6ef2b9f19e04ca9 --- /dev/null +++ b/doc/paddle/api/paddle/distribution/Distribution_cn.rst @@ -0,0 +1,49 @@ +.. _cn_api_distribution_Distribution: + +Distribution +------------------------------- + +.. py:class:: paddle.distribution.Distribution() + + + + +概率分布的抽象基类，在具体的分布中实现具体功能。 + + +.. py:function:: sample() + +从分布中采样 + +.. py:function:: entropy() + +分布的信息熵 + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Tensor) - 输入张量。 + +.. py:function:: probs(value) + +概率密度函数 + +参数： + - **value** (Tensor) - 输入张量。 + +.. py:function:: kl_divergence(other) + +两个分布之间的KL散度。 + +参数： + - **other** (Distribution) - Distribution的实例。 + + + + + + + + diff --git a/doc/paddle/api/paddle/distribution/Normal_cn.rst b/doc/paddle/api/paddle/distribution/Normal_cn.rst index a7ae0fe063be50f8af93a4197f68c09157a17733..c1bc0c8b57648787594e35f9ae9c9469e8eca81d 100644 --- a/doc/paddle/api/paddle/distribution/Normal_cn.rst +++ b/doc/paddle/api/paddle/distribution/Normal_cn.rst @@ -1,16 +1,128 @@ -.. _cn_api_fluid_initializer_Normal: +.. _cn_api_distribution_Normal: Normal ------------------------------- -.. py:attribute:: paddle.fluid.initializer.Normal +.. py:class:: paddle.distribution.Normal(loc, scale, name=None) + + + + +正态分布 + +数学公式： + +.. math:: + + pdf(x; \mu, \sigma) = \frac{1}{Z}e^{\frac {-0.5 (x - \mu)^2} {\sigma^2} } + + Z = (2 \pi \sigma^2)^{0.5} + +上面的数学公式中： + +:math:`loc = \mu` : 平均值。 +:math:`scale = \sigma` : 标准差。 +:math:`Z`: 正态分布常量。 + +参数： + - **loc** (int|float|list|numpy.ndarray|Tensor) - 正态分布平均值。数据类型为int、float32、list、numpy.ndarray或Tensor。 + - **scale** (int|float|list|numpy.ndarray|Tensor) - 正态分布标准差。数据类型为int、float32、list、numpy.ndarray或Tensor。 + - **name** (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + from paddle.distribution import Normal + + paddle.disable_static() + # Define a single scalar Normal distribution. + dist = Normal(loc=0., scale=3.) + # Define a batch of two scalar valued Normals. + # The first has mean 1 and standard deviation 11, the second 2 and 22. + dist = Normal(loc=[1., 2.], scale=[11., 22.]) + # Get 3 samples, returning a 3 x 2 tensor. + dist.sample([3]) + + # Define a batch of two scalar valued Normals. + # Both have mean 1, but different standard deviations. + dist = Normal(loc=1., scale=[11., 22.]) + + # Complete example + value_npdata = np.array([0.8], dtype="float32") + value_tensor = paddle.to_tensor(value_npdata) + + normal_a = Normal([0.], [1.]) + normal_b = Normal([0.5], [2.]) + sample = normal_a.sample([2]) + # a random tensor created by normal distribution with shape: [2, 1] + entropy = normal_a.entropy() + # [1.4189385] with shape: [1] + lp = normal_a.log_prob(value_tensor) + # [-1.2389386] with shape: [1] + p = normal_a.probs(value_tensor) + # [0.28969154] with shape: [1] + kl = normal_a.kl_divergence(normal_b) + # [0.34939718] with shape: [1] + + +.. py:function:: sample(shape, seed=0) + +生成指定维度的样本 + +参数： + - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。 + - **seed** (int) - 长整型数。 + +返回：预先设计好维度的张量, 数据类型为float32 + +返回类型：Tensor + +.. py:function:: entropy() + +信息熵 + +返回：正态分布的信息熵, 数据类型为float32 + +返回类型：Tensor + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Tensor) - 输入张量。数据类型为float32或float64。 + +返回：对数概率, 数据类型与value相同 + +返回类型：Tensor + +.. py:function:: probs(value) + +概率密度函数 + +参数： + - **value** (Tensor) - 输入张量。数据类型为float32或float64。 + +返回：概率, 数据类型与value相同 + +返回类型：Tensor + +.. py:function:: kl_divergence(other) + +两个正态分布之间的KL散度。 + +参数： + - **other** (Normal) - Normal的实例。 + +返回：两个正态分布之间的KL散度, 数据类型为float32 + +返回类型：Tensor -:alias_main: paddle.nn.initializer.Normal -:alias: paddle.nn.initializer.Normal -:old_api: paddle.fluid.initializer.Normal -``NormalInitializer`` 的别名 diff --git a/doc/paddle/api/paddle/distribution/Uniform_cn.rst b/doc/paddle/api/paddle/distribution/Uniform_cn.rst index 48a7efeeeddd34a99effca7c37e1c8dea99bf761..382d1e9c66ff2691e045caf41f37241f21ba5978 100644 --- a/doc/paddle/api/paddle/distribution/Uniform_cn.rst +++ b/doc/paddle/api/paddle/distribution/Uniform_cn.rst @@ -1,17 +1,115 @@ -.. _cn_api_fluid_initializer_Uniform: +.. _cn_api_distribution_Uniform: Uniform ------------------------------- -.. py:attribute:: paddle.fluid.initializer.Uniform +.. py:class:: paddle.distribution.Uniform(low, high, name=None) -:alias_main: paddle.nn.initializer.Uniform -:alias: paddle.nn.initializer.Uniform -:old_api: paddle.fluid.initializer.Uniform -``UniformInitializer`` 的别名 +均匀分布 + +概率密度函数（pdf）为： + +.. math:: + + pdf(x; a, b) = \frac{1}{Z}, a <=x < b + + Z = b - a + +上面的数学公式中： + +:math:`low = a` 。 +:math:`high = b` 。 +:math:`Z`: 正态分布常量。 + +参数low和high的维度必须能够支持广播。 + +参数： + - **low** (int|float|list|numpy.ndarray|Tensor) - 均匀分布的下边界。数据类型为int、float32、list、numpy.ndarray或Tensor。 + - **high** (int|float|list|numpy.ndarray|Tensor) - 均匀分布的上边界。数据类型为int、float32、list、numpy.ndarray或Tensor。 + - **name** (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + from paddle.distribution import Uniform + + paddle.disable_static() + # Without broadcasting, a single uniform distribution [3, 4]: + u1 = Uniform(low=3.0, high=4.0) + # 2 distributions [1, 3], [2, 4] + u2 = Uniform(low=[1.0, 2.0], high=[3.0, 4.0]) + # 4 distributions + u3 = Uniform(low=[[1.0, 2.0], [3.0, 4.0]], + high=[[1.5, 2.5], [3.5, 4.5]]) + + # With broadcasting: + u4 = Uniform(low=3.0, high=[5.0, 6.0, 7.0]) + + # Complete example + value_npdata = np.array([0.8], dtype="float32") + value_tensor = paddle.to_tensor(value_npdata) + + uniform = Uniform([0.], [2.]) + + sample = uniform.sample([2]) + # a random tensor created by uniform distribution with shape: [2, 1] + entropy = uniform.entropy() + # [0.6931472] with shape: [1] + lp = uniform.log_prob(value_tensor) + # [-0.6931472] with shape: [1] + p = uniform.probs(value_tensor) + # [0.5] with shape: [1] + + +.. py:function:: sample(shape, seed=0) + +生成指定维度的样本 + +参数： + - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。 + - **seed** (int) - 长整型数。 + +返回：预先设计好维度的张量, 数据类型为float32 + +返回类型：Tensor + +.. py:function:: entropy() + +信息熵 + +返回：均匀分布的信息熵, 数据类型为float32 + +返回类型：Tensor + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Tensor) - 输入张量。数据类型为float32或float64。 + +返回：对数概率, 数据类型与value相同 + +返回类型：Tensor + +.. py:function:: probs(value) + +概率密度函数 + +参数： + - **value** (Tensor) - 输入张量。数据类型为float32或float64。 + +返回：概率, 数据类型与value相同 + +返回类型：Tensor + + diff --git a/doc/paddle/api/paddle/fluid/DistributeTranspilerConfig_cn.rst b/doc/paddle/api/paddle/fluid/DistributeTranspilerConfig_cn.rst index 398aceb246145d47be589ac166159b4259bedc87..4a95daa6428ad1d9be20ae1edc6dd1a0a0549920 100644 --- a/doc/paddle/api/paddle/fluid/DistributeTranspilerConfig_cn.rst +++ b/doc/paddle/api/paddle/fluid/DistributeTranspilerConfig_cn.rst @@ -1,38 +1,47 @@ -.. _cn_api_fluid_DistributeTranspilerConfig: +.. _cn_api_fluid_transpiler_DistributeTranspilerConfig: DistributeTranspilerConfig ------------------------------- -.. py:class:: paddle.fluid.DistributeTranspilerConfig +.. py:class:: paddle.fluid.transpiler.DistributeTranspilerConfig +:api_attr: 声明式编程模式（静态图) +单机任务切换为分布式任务的配置类，用户可根据需求进行配置，如指定同步/异步训练，指定节点个数及模型切分逻辑。 + +返回：None + .. py:attribute:: slice_var_up (bool) -为多个Pserver（parameter server）将tensor切片, 默认为True。 +是否为Pserver将张量切片， 默认为True, bool类型属性， 默认为True。该参数将指定是否将参数/梯度切分后均匀分布于多个PServer上。slice_var_up为True的情况下，会将参数均匀切分后分布于多个PServer端，使每个PServer的负载相对均衡。 + .. py:attribute:: split_method (PSDispatcher) -可使用 RoundRobin 或者 HashName。 +参数分发的方式，当前支持的方法包括 :ref:`cn_api_fluid_transpiler_RoundRobin` 和 :ref:`cn_api_fluid_transpiler_HashName` 两种， 默认为RoundRobin。 -注意: 尝试选择最佳方法来达到Pserver间负载均衡。 +注意: 尝试选择最佳方法来达到负载均衡。 .. py:attribute:: min_block_size (int) -block中分割(split)出的元素个数的最小值。 +参数切片时，最小数据块的大小，默认为8192。 -注意: 根据：`issuecomment-369912156 `_ , 当数据块大小超过2MB时，我们可以有效地使用带宽。如果你想更改它，请详细查看 ``slice_variable`` 函数。 +注意: 根据：https://github.com/PaddlePaddle/Paddle/issues/8638#issuecomment-369912156 ， 当数据块大小超过2MB时，我们可以有效地使用带宽。如果你想更改它，请详细查看slice_variable函数。 **代码示例** .. code-block:: python - - import paddle.fluid as fluid - config = fluid.DistributeTranspilerConfig() - config.slice_var_up = True + from paddle.fluid.transpiler.ps_dispatcher import RoundRobin + import paddle.fluid as fluid + + config = fluid.DistributeTranspilerConfig() + config.slice_var_up = True + config.split_method = RoundRobin + config.min_block_size = 81920 diff --git a/doc/paddle/api/paddle/fluid/DistributeTranspiler_cn.rst b/doc/paddle/api/paddle/fluid/DistributeTranspiler_cn.rst index ab4fb17c706485902823d4bdc04c7e6c30498944..92ea6dfbfd198334767f5f0afc6c958dd38d23ea 100644 --- a/doc/paddle/api/paddle/fluid/DistributeTranspiler_cn.rst +++ b/doc/paddle/api/paddle/fluid/DistributeTranspiler_cn.rst @@ -3,16 +3,17 @@ DistributeTranspiler ------------------------------- -.. py:class:: paddle.fluid.DistributeTranspiler (config=None) +.. py:class:: paddle.fluid.transpiler.DistributeTranspiler (config=None) + +:api_attr: 声明式编程模式（静态图) 该类可以把fluid program转变为分布式数据并行计算的program, 有PServer和NCCL2两种模式。 在Pserver（全称：parameter server）模式下， 通过 ``transpile`` 将用于单机训练的 ``program`` 转译为可用于parameter server的分布式架构(即PServer,参数服务器)来进行训练的program。 -在NCCL2模式下, 通过 ``transpile`` 将用于单机训练的 ``program`` 转译为可用于NCCL2的分布式架构来进行训练的program。在NCCL2模式下，transpiler会在 ``startup_program`` 中附加一个 ``NCCL_ID`` 广播 -算子（broadcasting operators）来实现在该集群中所有工作结点共享``NCCL_ID`` 。 调用 ``transpile_nccl2`` 后， 你 **必须** 将 ``trainer_id`` , ``num_trainers`` 参数提供给 ``Executor`` 来启动NCCL2分布式模式。 +在NCCL2模式下, 通过 ``transpile`` 将用于单机训练的 ``program`` 转译为可用于NCCL2的分布式架构来进行训练的program。在NCCL2模式下，transpiler会在 ``startup_program`` 中附加一个 ``NCCL_ID`` 广播算子（broadcasting operators）来实现在该集群中所有工作结点共享``NCCL_ID`` 。 调用 ``transpile_nccl2`` 后， 你 **必须** 将 ``trainer_id`` , ``num_trainers`` 参数提供给 ``Executor`` 来启动NCCL2分布式模式。 参数： @@ -75,15 +76,14 @@ DistributeTranspiler 通过此方法，可根据用户配置将单机的program转换为当前节点可用的数据并行的分布式program。 -参数: +参数: - **trainer_id** (int) – 当前Trainer worker的id, 如果有n个Trainer worker, id 取值范围为0 ~ n-1 - - **program** (Program|None) – 待transpile（转译）的program, 缺省为 ``fluid.default_main_program()`` - - **startup_program** (Program|None) - 要转译的 ``startup_program`` ,默认为 ``fluid.default_startup_program()`` - - **pservers** (str) – 内容为Pserver列表的字符串，格式为：按逗号区分不同的Pserver，每个Pserver的格式为 *ip地址:端口号* + - **program** (Program|None) – 待transpile（转译）的main program, 默认为 ``fluid.default_main_program()`` + - **pservers** (str) – 内容为Pserver列表的字符串，格式为：按逗号区分不同的Pserver，每个Pserver的格式为 *ip地址:端口号* - **trainers** (int|str) – 在Pserver模式下，该参数指Trainer机的个数；在nccl2模式下，它是一个内容为Trainer终端列表的字符串 - **sync_mode** (bool) – 是否做同步训练(synchronous training), 默认为True - - **startup_program** (Program|None) – 待transpile（转译）的startup_program，默认为 ``fluid.default_main_program()`` - - **current_endpoint** (str) – 当需要把program转译（transpile）至NCCL2模式下时，需要将当前endpoint（终端）传入该参数。PServer模型下，当用户需要使用增量训练时，必须要指定该参数。 + - **startup_program** (Program|None) – 待transpile（转译）的startup program，默认为 ``fluid.default_startup_program()`` + - **current_endpoint** (str) – 当需要把program转译（transpile）至NCCL2模式时，需要将当前endpoint（终端）传入该参数。PServer模型下，当用户需要使用增量训练时，必须要指定该参数。 返回：None @@ -104,7 +104,13 @@ DistributeTranspiler .. py:method:: get_trainer_program(wait_port=True) -该方法可以得到Trainer侧的program。 +该方法可以得到Trainer侧的program。Trainer侧的program相较于原始的单机执行的program，主要有以下不同: + + - 删除了参数更新optimizer相关op，参数的更新由Pserver（参数服务器）执行 + - 在每个参数的反向梯度计算op后，添加了 ``Send_op`` 与 ``Recv_op`` ，用于发送参数的梯度与接受更新后的参数 + +参数: + - **wait_port** (bool,默认值True) - 是否等待参数服务器准备就绪后再返回program 返回: Trainer侧的program @@ -127,11 +133,15 @@ DistributeTranspiler .. py:method:: get_pserver_program(endpoint) -该方法可以得到Pserver（参数服务器）侧的程序 - -参数: +该方法可以得到Pserver（参数服务器）侧的program。Pserver侧的program相较于原始的单机执行的program，主要有以下不同: + + - 仅包含参数更新optimizer相关op，与分布式通信相关op + - 0号block仅包含变量的定义及 ``listen_and_serv_op`` + - Pserver为每个需要进行更新的参数新建了一个独立的block + +参数: - **endpoint** (str) – 当前Pserver终端 - + 返回: 当前Pserver需要执行的program 返回类型: Program @@ -155,16 +165,16 @@ DistributeTranspiler .. py:method:: get_pserver_programs(endpoint) -该方法可以得到Pserver侧用于分布式训练的 ``main_program`` 和 ``startup_program`` 。 +该方法可以得到Pserver侧用于分布式训练的 ``main_program`` 和 ``startup_program`` 。该函数返回的 ``main_program`` 与函数 ``get_pserver_program`` 的返回值一致。 -参数: +参数: - **endpoint** (str) – 当前Pserver终端 返回: (main_program, startup_program), “Program”类型的元组 -返回类型: tuple - - +返回类型: tuple + + **代码示例** .. code-block:: python @@ -187,7 +197,7 @@ DistributeTranspiler **该函数已停止使用** 获取当前Pserver的startup_program，如果有多个被分散到不同blocks的变量，则修改operator的输入变量。 -参数: +参数: - **endpoint** (str) – 当前Pserver终端 - **pserver_program** (Program) – 已停止使用。 先调用get_pserver_program - **startup_program** (Program) – 已停止使用。应在初始化时传入startup_program @@ -205,7 +215,7 @@ DistributeTranspiler current_endpoint = "192.168.0.1:6174" trainer_id = 0 trainers = 4 - + t = fluid.DistributeTranspiler() t.transpile(trainer_id, pservers=pserver_endpoints, trainers=trainers) pserver_program = t.get_pserver_program(current_endpoint) diff --git a/doc/paddle/api/paddle/fluid/clip_cn.rst b/doc/paddle/api/paddle/fluid/clip_cn.rst deleted file mode 100644 index 071fe323ffdf8de41a454669e3b23e2f7f976a4b..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/clip_cn.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _cn_api_fluid_layers_clip: - -clip -------------------------------- - -.. py:function:: paddle.fluid.layers.clip(x, min, max, name=None) - -:alias_main: paddle.nn.clip -:alias: paddle.nn.clip,paddle.nn.clip.clip -:old_api: paddle.fluid.layers.clip - - - -该OP对输入Tensor每个元素的数值进行裁剪，使得输出Tensor元素的数值被限制在区间[min, max]内。具体的计算公式为如下。 - -.. math:: - - Out = MIN(MAX(x,min),max) - - - -参数： - - **x** (Variable)- 多维Tensor，数据类型为float32 - - **min** (float)- 最小值，输入Tensor中小于该值的元素由min代替。 - - **max** (float)- 最大值，输入Tensor中大于该值的元素由max替换。 - - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 - -返回： 对元素的数值进行裁剪之后的Tesnor，与输入x具有相同的shape和数据类型 - -返回类型：Variable - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - input = fluid.layers.data( - name='data', shape=[1], dtype='float32') - reward = fluid.layers.clip(x=input, min=-1.0, max=1.0) - - diff --git a/doc/paddle/api/paddle/fluid/contrib/BeamSearchDecoder_cn.rst b/doc/paddle/api/paddle/fluid/contrib/BeamSearchDecoder_cn.rst index 67e7312aaef57ff031e410031aecc73bc50c265f..d62d05ae86bda97df4fe06e328653df5251db4cd 100644 --- a/doc/paddle/api/paddle/fluid/contrib/BeamSearchDecoder_cn.rst +++ b/doc/paddle/api/paddle/fluid/contrib/BeamSearchDecoder_cn.rst @@ -20,7 +20,7 @@ BeamSearchDecoder - **start_token** (int) - 起始标记id。 - **end_token** (int) - 结束标记id。 - **beam_size** (int) - 在beam search中使用的beam宽度。 - - **embedding_fn** (可选) - 处理选中的候选id的接口。通常，它是一个将词id转换为词嵌入的嵌入层，函数的返回值作为 :code:`cell.call` 接口的 :code:`input` 参数。如果 :code:`embedding_fn` 未提供，则必须在 :code:`cell.call` 中实现词嵌入转换。默认值None。 + - **embedding_fn** (可选) - 处理选中的候选id的接口。它通常是一个将词id转换为词嵌入的嵌入层，其返回值将作为 :code:`cell.call` 接口的 :code:`input` 参数。**注意** ，这里要使用 :ref:`cn_api_fluid_embedding` 而非 :ref:`cn_api_fluid_layers_embedding`，因为选中的id的形状是 :math:`[batch\_size, beam\_size]` ，如果使用后者则还需要在这里提供unsqueeze。如果 :code:`embedding_fn` 未提供，则必须在 :code:`cell.call` 中实现词嵌入转换。默认值None。 - **output_fn** (可选) - 处理cell输出的接口，在计算得分和选择候选标记id之前使用。默认值None。 **示例代码** @@ -123,7 +123,7 @@ BeamSearchDecoder 参数： - **initial_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。调用者提供的参数。 -返回：一个元组 :code:`(initial_inputs, initial_states, finished)`。:code:`initial_inputs` 是一个tensor，当 :code:`embedding_fn` 为None时，由 :code:`start_token` 填充，形状为 :math:`[batch\_size,beam\_size,1]` ；否则使用 :code:`embedding_fn(t)` 返回的值。:code:`initial_states` 是tensor变量的嵌套结构(命名元组，字段包括 :code:`cell_states，log_probs，finished，lengths`)，其中 :code:`log_probs，finished，lengths` 都含有一个tensor，形状为 :math:`[batch\_size, beam\_size]`，数据类型为float32，bool，int64。:code:`cell_states` 具有与输入参数 :code:`initial_cell_states` 相同结构的值，但形状扩展为 :math:`[batch\_size,beam\_size,...]`。 :code:`finished` 是一个布尔型tensor，由False填充，形状为 :math:`[batch\_size,beam\_size]`。 +返回：一个元组 :code:`(initial_inputs, initial_states, finished)`。:code:`initial_inputs` 是一个tensor，当 :code:`embedding_fn` 为None时，该tensor t的形状为 :math:`[batch\_size,beam\_size]` ，值为 :code:`start_token` ；否则使用 :code:`embedding_fn(t)` 返回的值。:code:`initial_states` 是tensor变量的嵌套结构(命名元组，字段包括 :code:`cell_states，log_probs，finished，lengths`)，其中 :code:`log_probs，finished，lengths` 都含有一个tensor，形状为 :math:`[batch\_size, beam\_size]`，数据类型为float32，bool，int64。:code:`cell_states` 具有与输入参数 :code:`initial_cell_states` 相同结构的值，但形状扩展为 :math:`[batch\_size,beam\_size,...]`。 :code:`finished` 是一个布尔型tensor，由False填充，形状为 :math:`[batch\_size,beam\_size]`。 返回类型：tuple @@ -135,7 +135,7 @@ BeamSearchDecoder - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 - **logits** (Variable) - 形状为 :math:`[batch\_size,beam\_size,vocab\_size]` 的tensor，表示当前时间步的logits。其数据类型为float32。 - **next_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。它的结构，形状和数据类型与 :code:`initialize()` 的返回值 :code:`initial_states` 中的 :code:`cell_states` 相同。它代表该cell的下一个状态。 - - **beam_state** (Variable) - tensor变量的结构。在第一个解码步骤与 :code:`initialize()` 返回的 :code:`initial_states` 同，其他步骤与 :code:`initialize()` 返回的 :code:`beam_search_state` 相同。 + - **beam_state** (Variable) - tensor变量的结构。在第一个解码步骤与 :code:`initialize()` 返回的 :code:`initial_states` 同，其他步骤与 :code:`step()` 返回的 :code:`beam_search_state` 相同。 返回：一个元组 :code:`(beam_search_output, beam_search_state)`。:code:`beam_search_output` 是tensor变量的命名元组，字段为 :code:`scores，predicted_ids parent_ids`。其中 :code:`scores，predicted_ids，parent_ids` 都含有一个tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为float32 ，int64，int64。:code:`beam_search_state` 具有与输入参数 :code:`beam_state` 相同的结构，形状和数据类型。 @@ -146,9 +146,9 @@ BeamSearchDecoder 执行beam search解码步骤，该步骤使用 :code:`cell` 来计算概率，然后执行beam search步骤以计算得分并选择候选标记ID。 参数： - - **time** (Variable) - 调用者提供的形状为[1]的int64tensor，表示当前解码的时间步长。 + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。。 - **inputs** (Variable) - tensor变量。在第一个解码时间步时与由 :code:`initialize()` 返回的 :code:`initial_inputs` 相同，其他时间步与由 :code:`step()` 返回的 :code:`next_inputs` 相同。 - - **States** (Variable) - tensor变量的结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`beam_search_state` 相同。 + - **states** (Variable) - tensor变量的结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`beam_search_state` 相同。 - **kwargs** - 附加的关键字参数，由调用者提供。 返回：一个元组 :code:`(beam_search_output，beam_search_state，next_inputs，finish)` 。:code:`beam_search_state` 和参数 :code:`states` 具有相同的结构，形状和数据类型。 :code:`next_inputs` 与输入参数 :code:`inputs` 具有相同的结构，形状和数据类型。 :code:`beam_search_output` 是tensor变量的命名元组(字段包括 :code:`scores，predicted_ids，parent_ids` )，其中 :code:`scores，predicted_ids，parent_ids` 都含有一个tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为float32 ，int64，int64。:code:`finished` 是一个bool类型的tensor，形状为 :math:`[batch\_size,beam\_size]`。 @@ -167,12 +167,3 @@ BeamSearchDecoder 返回：一个元组 :code:`(predicted_ids, final_states)`。:code:`predicted_ids` 是一个tensor，形状为 :math:`[time\_step，batch\_size,beam\_size]`，数据类型为int64。:code:`final_states` 与输入参数 :code:`final_states` 相同。 返回类型：tuple - -.. py:method:: output_dtype() - -用于beam search输出的数据类型的嵌套结构。它是一个命名元组，字段包括 :code:`scores, predicted_ids, parent_ids`。 - -参数：无。 - -返回：用于beam search输出的数据类型的命名元组。 - diff --git a/doc/paddle/api/paddle/fluid/data_cn.rst b/doc/paddle/api/paddle/fluid/data_cn.rst index f250c9438581e2cddaebe4f72c8adb5c6821cdb9..14a6ab6ea1d94dcdc3586417ef9c85db98783c74 100644 --- a/doc/paddle/api/paddle/fluid/data_cn.rst +++ b/doc/paddle/api/paddle/fluid/data_cn.rst @@ -6,10 +6,6 @@ data .. py:function:: paddle.fluid.data(name, shape, dtype='float32', lod_level=0) -:api_attr: 声明式编程模式（静态图) -:alias_main: paddle.nn.data -:alias: paddle.nn.data,paddle.nn.input.data -:old_api: paddle.fluid.data diff --git a/doc/paddle/api/paddle/fluid/dygraph/Conv2D_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/Conv2D_cn.rst index c09cb6548135d5b713d3c63f01ca321311e09187..3e81c4a31738d78234527178a1408c7cc03519ef 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/Conv2D_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/Conv2D_cn.rst @@ -46,7 +46,7 @@ Conv2D 参数： - **num_channels** (int) - 输入图像的通道数。 - - **num_fliters** (int) - 滤波器的个数，和输出特征图个数相同。 + - **num_filters** (int) - 滤波器的个数，和输出特征图个数相同。 - **filter_size** (int|tuple) - 滤波器大小。如果 ``filter_size`` 是一个元组，则必须包含两个整型数，分别表示滤波器高度和宽度。否则，表示滤波器高度和宽度均为 ``filter_size`` 。 - **stride** (int|tuple, 可选) - 步长大小。如果 ``stride`` 为元组，则必须包含两个整型数，分别表示垂直和水平滑动步长。否则，表示垂直和水平滑动步长均为 ``stride`` 。默认值：1。 - **padding** (int|tuple, 可选) - 填充大小。如果 ``padding`` 为元组，则必须包含两个整型数，分别表示竖直和水平边界填充大小。否则，表示竖直和水平边界填充大小均为 ``padding`` 。默认值：0。 diff --git a/doc/paddle/api/paddle/fluid/dygraph/base/grad_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/base/grad_cn.rst deleted file mode 100644 index bc73f2e14a68bf2be3a68d43c24e39bdd0ad1337..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/dygraph/base/grad_cn.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _cn_api_fluid_dygraph_grad: - -grad -------------------------------- - -**注意：该API仅支持【动态图】模式** - -.. py:method:: paddle.fluid.dygraph.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False, no_grad_vars=None, backward_strategy=None) - -对于每个 `inputs` ，计算所有 `outputs` 相对于其的梯度和。 - -参数: - - **outputs** (Variable|list(Variable)|tuple(Variable)) – 用于计算梯度的图的输出变量，或多个输出变量构成的list/tuple。 - - **inputs** (Variable|list(Variable)|tuple(Variable)) - 用于计算梯度的图的输入变量，或多个输入变量构成的list/tuple。该API的每个返回值对应每个 `inputs` 的梯度。 - - **grad_outputs** (Variable|list(Variable|None)|tuple(Variable|None), 可选) - `outputs` 变量梯度的初始值。若 `grad_outputs` 为None，则 `outputs` 梯度的初始值均为全1的Tensor。若 `grad_outputs` 不为None，它必须与 `outputs` 的长度相等，此时，若 `grad_outputs` 的第i个元素为None，则第i个 `outputs` 的梯度初始值为全1的Tensor；若 `grad_outputs` 的第i个元素为Variable，则第i个 `outputs` 的梯度初始值为 `grad_outputs` 的第i个元素。默认值为None。 - - **retain_graph** (bool, 可选) - 是否保留计算梯度的前向图。若值为True，则前向图会保留，用户可对同一张图求两次反向。若值为False，则前向图会释放。默认值为None，表示值与 `create_graph` 相等。 - - **create_graph** (bool, 可选) - 是否创建计算过程中的反向图。若值为True，则可支持计算高阶导数。若值为False，则计算过程中的反向图会释放。默认值为False。 - - **only_inputs** (bool, 可选) - 是否只计算 `inputs` 的梯度。若值为False，则图中所有叶节点变量的梯度均会计算，并进行累加。若值为True，则只会计算 `inputs` 的梯度。默认值为True。only_inputs=False功能正在开发中，目前尚不支持。 - - **allow_unused** (bool, 可选) - 决定当某些 `inputs` 变量不在计算图中时抛出错误还是返回None。若某些 `inputs` 变量不在计算图中（即它们的梯度为None），则当allowed_unused=False时会抛出错误，当allow_unused=True时会返回None作为这些变量的梯度。默认值为False。 - - **no_grad_vars** (Variable|list(Variable)|tuple(Variable)|set(Variable), 可选) - 指明不需要计算梯度的变量。默认值为None。 - - **backward_strategy** (BackwardStrategy, 可选) - 计算梯度的策略。详见 :ref:`cn_api_fluid_dygraph_BackwardStrategy` 。默认值为None。 - -返回: 变量构成的tuple，其长度等于 `inputs` 中的变量个数，且第i个返回的变量是所有 `outputs` 相对于第i个 `inputs` 的梯度之和。 - -返回类型: tuple - -**示例代码 1** - .. code-block:: python - - import paddle.fluid as fluid - - def test_dygraph_grad(create_graph): - with fluid.dygraph.guard(): - x = fluid.layers.ones(shape=[1], dtype='float32') - x.stop_gradient = False - y = x * x - - # Since y = x * x, dx = 2 * x - dx = fluid.dygraph.grad( - outputs=[y], - inputs=[x], - create_graph=create_graph, - retain_graph=True)[0] - - z = y + dx - - # If create_graph = False, the gradient of dx - # would not be backpropagated. Therefore, - # z = x * x + dx, and x.gradient() = 2 * x = 2.0 - - # If create_graph = True, the gradient of dx - # would be backpropagated. Therefore, - # z = x * x + dx = x * x + 2 * x, and - # x.gradient() = 2 * x + 2 = 4.0 - - z.backward() - return x.gradient() - - print(test_dygraph_grad(create_graph=False)) # [2.] - print(test_dygraph_grad(create_graph=True)) # [4.] - -**示例代码 2** - .. code-block:: python - - import paddle.fluid as fluid - - fluid.enable_dygraph() - - def test_dygraph_grad(grad_outputs=None): - x = fluid.layers.fill_constant(shape=[1], value=2.0, dtype='float32') - x.stop_gradient = False - - y1 = x * x - y2 = x * 3 - - # If grad_outputs=None, dy1 = [1], dy2 = [1]. - # If grad_outputs=[g1, g2], then: - # - dy1 = [1] if g1 is None else g1 - # - dy2 = [1] if g2 is None else g2 - - # Since y1 = x * x, dx = 2 * x * dy1. - # Since y2 = x * 3, dx = 3 * dy2. - # Therefore, the final result would be: - # dx = 2 * x * dy1 + 3 * dy2 = 4 * dy1 + 3 * dy2. - - dx = fluid.dygraph.grad( - outputs=[y1, y2], - inputs=[x], - grad_outputs=grad_outputs)[0] - - return dx.numpy() - - THREE = fluid.layers.fill_constant(shape=[1], value=3.0, dtype='float32') - FOUR = fluid.layers.fill_constant(shape=[1], value=4.0, dtype='float32') - - # dy1 = [1], dy2 = [1] - print(test_dygraph_grad(None)) # [7.] - - # dy1 = [1], dy2 = [4] - print(test_dygraph_grad([None, FOUR])) # [16.] - - # dy1 = [4], dy2 = [1] - print(test_dygraph_grad([FOUR, None])) # [19.] - - # dy1 = [3], dy2 = [4] - print(test_dygraph_grad([THREE, FOUR])) # [24.] \ No newline at end of file diff --git a/doc/paddle/api/paddle/fluid/dygraph/base/no_grad_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/base/no_grad_cn.rst index e93287287b29e61256e51249792d57390033d040..9c84e82da4a895d898ea34154d71a19190f744eb 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/base/no_grad_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/base/no_grad_cn.rst @@ -4,48 +4,49 @@ no_grad ------------------------------- -.. py:method:: paddle.fluid.dygraph.no_grad(func=None) +.. py:class:: paddle.fluid.dygraph.no_grad :api_attr: 命令式编程模式（动态图) - +:old_api: paddle.fluid.dygraph.no_grad 创建一个上下文来禁用动态图梯度计算。在此模式下，每次计算的结果都将具有stop_gradient=True。 -也可以用作一个装饰器（确保不要用括号来初始化）。 +也可以用作一个装饰器（需要创建实例对象作为装饰器）。 **代码示例** .. code-block:: python - import numpy as np import paddle.fluid as fluid + paddle.enable_imperative() + # 用作生成器 + data = np.array([[2, 3], [4, 5]]).astype('float32') - with fluid.dygraph.guard(): - l0 = fluid.Linear(2, 2) # l0.weight.gradient() is None - l1 = fluid.Linear(2, 2) - with fluid.dygraph.no_grad(): - # l1.weight.stop_gradient is False - tmp = l1.weight * 2 # tmp.stop_gradient is True - x = fluid.dygraph.to_variable(data) - y = l0(x) + tmp - o = l1(y) - o.backward() - print(tmp.gradient() is None) # True - print(l0.weight.gradient() is None) # False - + l0 = fluid.Linear(2, 2) # l0.weight.gradient() is None + l1 = fluid.Linear(2, 2) + with fluid.no_grad(): + # l1.weight.stop_gradient is False + tmp = l1.weight * 2 # tmp.stop_gradient is True + x = fluid.dygraph.to_variable(data) + y = l0(x) + tmp + o = l1(y) + o.backward() + print(tmp.gradient() is None) # True + print(l0.weight.gradient() is None) # False + # 用作装饰器 - @fluid.dygraph.no_grad + + @fluid.no_grad() def test_layer(): - with fluid.dygraph.guard(): - inp = np.ones([3, 1024], dtype='float32') - t = fluid.dygraph.base.to_variable(inp) - linear1 = fluid.Linear(1024, 4, bias_attr=False) - linear2 = fluid.Linear(4, 4) - ret = linear1(t) - dy_ret = linear2(ret) + inp = np.ones([3, 1024], dtype='float32') + t = fluid.dygraph.base.to_variable(inp) + linear1 = fluid.Linear(1024, 4, bias_attr=False) + linear2 = fluid.Linear(4, 4) + ret = linear1(t) + dy_ret = linear2(ret) test_layer() diff --git a/doc/paddle/api/paddle/fluid/dygraph/checkpoint/load_dygraph_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/checkpoint/load_dygraph_cn.rst index f9e86e0108e5d982e1a9e58ad34921496ab922cb..39b18d7830eaafa66c6a99a770cf8e85b8fc32b5 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/checkpoint/load_dygraph_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/checkpoint/load_dygraph_cn.rst @@ -1,27 +1,27 @@ .. _cn_api_fluid_dygraph_load_dygraph: -load ----- +load_dygraph +------------------------------- -.. py:function:: paddle.load(model_path, configs=None) +.. py:function:: paddle.fluid.dygraph.load_dygraph(model_path) :api_attr: 命令式编程模式（动态图) -该接口用于从磁盘中加载Layer和Optimizer的 ``state_dict`` ，该接口会同时加载 ``model_path + ".pdparams"`` 和 ``model_path + ".pdopt"`` 中的内容。 -.. note:: - 由于一些历史原因，如果从 ``paddle.io.save_inference_model`` 的存储结果中载入 ``state_dict`` ，动态图模式下参数的结构性变量名将无法被恢复。并且在将载入的 ``state_dict`` 配置到当前Layer中时，需要配置 ``Layer.set_state_dict`` 的参数 ``use_structured_name=False`` 。 + +该接口尝试从磁盘中加载参数或优化器的 ``dict`` 。 + +该接口会同时加载 ``model_path + ".pdparams"`` 和 ``model_path + ".pdopt"`` 中的内容。 参数: - - **model_path** (str) – 保存state_dict的文件前缀。该路径不应该包括后缀 ``.pdparams`` 或 ``.pdopt``。 - - **configs** (SaveLoadConfig, 可选) - 用于指定额外配置选项的 :ref:`cn_api_fluid_dygraph_jit_SaveLoadConfig` 对象，这些选项主要是用于兼容 ``paddle.io.save_inference_model`` 存储模型的格式。默认为 ``None``。 + - **model_path** (str) – 保存state_dict的文件前缀。该路径不应该包括后缀 ``.pdparams`` 或 ``.pdopt``。 -返回: 两个 ``dict`` ，即从文件中恢复的模型参数 ``dict`` 和优化器参数 ``dict``，如果只找到其中一个的存储文件，另一个返回None +返回: 两个 ``dict`` ，即从文件中恢复的参数 ``dict`` 和优化器 ``dict`` -- param_dict: 从文件中恢复的模型参数 ``dict`` -- opt_dict: 从文件中恢复的优化器参数 ``dict`` +- para_dict: 从文件中恢复的参数 ``dict`` +- opti_dict: 从文件中恢复的优化器 ``dict`` 返回类型: tuple(dict, dict) @@ -29,24 +29,18 @@ load .. code-block:: python - import paddle - - paddle.disable_static() - - emb = paddle.nn.Embedding([10, 10]) - - state_dict = emb.state_dict() - paddle.save(state_dict, "paddle_dy") + import paddle.fluid as fluid - scheduler = paddle.optimizer.lr_scheduler.NoamLR( - d_model=0.01, warmup_steps=100, verbose=True) - adam = paddle.optimizer.Adam( - learning_rate=scheduler, - parameters=emb.parameters()) - state_dict = adam.state_dict() - paddle.save(state_dict, "paddle_dy") + with fluid.dygraph.guard(): + emb = fluid.dygraph.Embedding([10, 10]) + state_dict = emb.state_dict() + fluid.save_dygraph( state_dict, "paddle_dy") + adam = fluid.optimizer.Adam( learning_rate = fluid.layers.noam_decay( 100, 10000) , + parameter_list = emb.parameters() ) + state_dict = adam.state_dict() + fluid.save_dygraph( state_dict, "paddle_dy") - para_state_dict, opti_state_dict = paddle.load("paddle_dy") + para_state_dict, opti_state_dict = fluid.load_dygraph( "paddle_dy") diff --git a/doc/paddle/api/paddle/fluid/dygraph/enabled_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/enabled_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e5716e76456a99ba5724369d4c2aaba7bfa129f8 --- /dev/null +++ b/doc/paddle/api/paddle/fluid/dygraph/enabled_cn.rst @@ -0,0 +1,25 @@ +.. _cn_api_fluid_dygraph_enabled: + +enabled +------------------------------- + +.. py:method:: paddle.fluid.dygraph.enabled() + +这个函数用于检查程序是否运行在动态图模式。你可以使用 :ref:`cn_api_fluid_dygraph_guard` api进入动态图模式。或者使用 :ref:`cn_api_fluid_enable_dygraph` 和 :ref:`cn_api_fluid_disable_dygraph` api打开、关闭动态图模式。 + +注意： `fluid.dygraph.enabled` 实际上调用了 :ref:`cn_api_fluid_in_dygraph_mode` api，所以推荐使用 :ref:`cn_api_fluid_in_dygraph_mode` api。 + +返回： 程序是否运行在动态图模式。 + +返回类型： bool + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + + fluid.enable_dygraph() # Now we are in dygragh mode + print(fluid.dygraph.enabled()) # True + fluid.disable_dygraph() + print(fluid.dygraph.enabled()) # False diff --git a/doc/paddle/api/paddle/fluid/dygraph/guard_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/guard_cn.rst index 651e8b6b5998545b5b8cf6553bc39c5b59495c25..7c457eb15118baf6823be9e404fc2fa053b6a2f6 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/guard_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/guard_cn.rst @@ -1,35 +1,35 @@ -.. _cn_api_fluid_dygraph_guard: +.. _cn_api_fluid_unique_name_guard: guard ------------------------------- +.. py:function:: paddle.fluid.unique_name.guard(new_generator=None) -.. py:function:: paddle.fluid.dygraph.guard(place=None) -:api_attr: 命令式编程模式（动态图) +该接口用于更改命名空间，与with语句一起使用。使用后，在with语句的上下文中使用新的命名空间，调用generate接口时相同前缀的名称将从0开始重新编号。 -通过with语句创建一个dygraph运行的context，执行context代码。 +参数: + - **new_generator** (str|bytes, 可选) - 新命名空间的名称。请注意，Python2中的str在Python3中被区分为str和bytes两种，因此这里有两种类型。 缺省值为None，若不为None，new_generator将作为前缀添加到generate接口产生的唯一名称中。 -参数： - - **place** (fluid.CPUPlace|fluid.CUDAPlace, 可选) – 动态图执行的设备，可以选择cpu，gpu，如果用户未制定，则根据用户paddle编译的方式来选择运行的设备，如果编译的cpu版本，则在cpu上运行，如果是编译的gpu版本，则在gpu上运行。默认值：None。 - -返回： None +返回: 无。 **代码示例** .. code-block:: python - import numpy as np - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - inp = np.ones([3, 1024], dtype='float32') - t = fluid.dygraph.base.to_variable(inp) - linear1 = fluid.Linear(1024, 4, bias_attr=False) - linear2 = fluid.Linear(4, 4) - ret = linear1(t) - dy_ret = linear2(ret) + import paddle.fluid as fluid + with fluid.unique_name.guard(): + name_1 = fluid.unique_name.generate('fc') + with fluid.unique_name.guard(): + name_2 = fluid.unique_name.generate('fc') + print(name_1, name_2) # fc_0, fc_0 + + with fluid.unique_name.guard('A'): + name_1 = fluid.unique_name.generate('fc') + with fluid.unique_name.guard('B'): + name_2 = fluid.unique_name.generate('fc') + print(name_1, name_2) # Afc_0, Bfc_0 diff --git a/doc/paddle/api/paddle/fluid/dygraph/io/TranslatedLayer_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/io/TranslatedLayer_cn.rst index 2f46906603077a254033c088587959f89f04d120..0924a155a0ffb8861dd0f233cf0b0eff3dd8b169 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/io/TranslatedLayer_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/io/TranslatedLayer_cn.rst @@ -15,180 +15,70 @@ TranslatedLayer .. code-block:: python import numpy as np - import paddle - import paddle.nn as nn - import paddle.optimizer as opt - - BATCH_SIZE = 16 - BATCH_NUM = 4 - EPOCH_NUM = 4 - - IMAGE_SIZE = 784 - CLASS_NUM = 10 - - # define a random dataset - class RandomDataset(paddle.io.Dataset): - def __init__(self, num_samples): - self.num_samples = num_samples - - def __getitem__(self, idx): - image = np.random.random([IMAGE_SIZE]).astype('float32') - label = np.random.randint(0, CLASS_NUM - 1, (1, )).astype('int64') + import paddle.fluid as fluid + from paddle.fluid.dygraph import Linear + from paddle.fluid.dygraph import declarative + BATCH_SIZE = 32 + BATCH_NUM = 20 + def random_batch_reader(): + def _get_random_images_and_labels(image_shape, label_shape): + image = np.random.random(size=image_shape).astype('float32') + label = np.random.random(size=label_shape).astype('int64') return image, label - - def __len__(self): - return self.num_samples - - class LinearNet(nn.Layer): - def __init__(self): + def __reader__(): + for _ in range(BATCH_NUM): + batch_image, batch_label = _get_random_images_and_labels( + [BATCH_SIZE, 784], [BATCH_SIZE, 1]) + yield batch_image, batch_label + return __reader__ + class LinearNet(fluid.dygraph.Layer): + def __init__(self, in_size, out_size): super(LinearNet, self).__init__() - self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM) - - @paddle.jit.to_static + self._linear = Linear(in_size, out_size) + @declarative def forward(self, x): return self._linear(x) - - def train(layer, loader, loss_fn, opt): - for epoch_id in range(EPOCH_NUM): - for batch_id, (image, label) in enumerate(loader()): - out = layer(image) - loss = loss_fn(out, label) - loss.backward() - opt.step() - opt.clear_grad() - print("Epoch {} batch {}: loss = {}".format( - epoch_id, batch_id, np.mean(loss.numpy()))) - - # enable dygraph mode - place = paddle.CPUPlace() - paddle.disable_static(place) - - # 1. train & save model. - - # create network - layer = LinearNet() - loss_fn = nn.CrossEntropyLoss() - adam = opt.Adam(learning_rate=0.001, parameters=layer.parameters()) - - # create data loader - dataset = RandomDataset(BATCH_NUM * BATCH_SIZE) - loader = paddle.io.DataLoader(dataset, - places=place, - batch_size=BATCH_SIZE, - shuffle=True, - drop_last=True, - num_workers=2) - - # train - train(layer, loader, loss_fn, adam) - - # save + # 开启命令式编程模式 + fluid.enable_dygraph() + # 1. 训练存储模型. + # 创建网络 + net = LinearNet(784, 1) + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=net.parameters()) + # 创建DataLoader + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + # 训练 + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = net(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + net.clear_gradients() model_path = "linear.example.model" - paddle.jit.save(layer, model_path) - - # 2. load model as TranslatedLayer - - # load - translated_layer = paddle.jit.load(model_path) - - # inference + fluid.dygraph.jit.save( + layer=net, + model_path=model_path, + input_spec=[img]) + # 2. 载入模型构建TranslatedLayer + translated_layer = fluid.dygraph.jit.load(model_path) + # 预测 translated_layer.eval() - x = paddle.randn([1, IMAGE_SIZE], 'float32') + x = fluid.dygraph.to_variable(np.random.random((1, 784)).astype('float32')) pred = translated_layer(x) - - # fine-tune + # fine-tune训练 translated_layer.train() - adam = opt.Adam(learning_rate=0.001, parameters=translated_layer.parameters()) - train(translated_layer, loader, loss_fn, adam) - - -.. py:method:: program(method_name='forward'): - -获取TranslatedLayer中指定方法对应的Program。 - -参数： - - **method_name** (string) - 要获取的Porgram对应的方法名。默认值为"forward"。 - -返回：Program - -返回类型：Program - -**示例代码：** - .. code-block:: python - - import numpy as np - import paddle - import paddle.nn as nn - import paddle.optimizer as opt - - BATCH_SIZE = 16 - BATCH_NUM = 4 - EPOCH_NUM = 4 - - IMAGE_SIZE = 784 - CLASS_NUM = 10 - - # define a random dataset - class RandomDataset(paddle.io.Dataset): - def __init__(self, num_samples): - self.num_samples = num_samples - - def __getitem__(self, idx): - image = np.random.random([IMAGE_SIZE]).astype('float32') - label = np.random.randint(0, CLASS_NUM - 1, (1, )).astype('int64') - return image, label - - def __len__(self): - return self.num_samples - - class LinearNet(nn.Layer): - def __init__(self): - super(LinearNet, self).__init__() - self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM) - - @paddle.jit.to_static - def forward(self, x): - return self._linear(x) - - def train(layer, loader, loss_fn, opt): - for epoch_id in range(EPOCH_NUM): - for batch_id, (image, label) in enumerate(loader()): - out = layer(image) - loss = loss_fn(out, label) - loss.backward() - opt.step() - opt.clear_grad() - print("Epoch {} batch {}: loss = {}".format( - epoch_id, batch_id, np.mean(loss.numpy()))) - - # enable dygraph mode - place = paddle.CPUPlace() - paddle.disable_static(place) - - # create network - layer = LinearNet() - loss_fn = nn.CrossEntropyLoss() - adam = opt.Adam(learning_rate=0.001, parameters=layer.parameters()) - - # create data loader - dataset = RandomDataset(BATCH_NUM * BATCH_SIZE) - loader = paddle.io.DataLoader(dataset, - places=place, - batch_size=BATCH_SIZE, - shuffle=True, - drop_last=True, - num_workers=2) - - # train - train(layer, loader, loss_fn, adam) - - # save - model_path = "linear.example.model" - paddle.jit.save(layer, model_path) - - # load - translated_layer = paddle.jit.load(model_path) - - # get program - program = translated_layer.program() - print(program) + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=translated_layer.parameters()) + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = translated_layer(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + translated_layer.clear_gradients() diff --git a/doc/paddle/api/paddle/fluid/dygraph/jit/declarative_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/jit/declarative_cn.rst index ce3a9294485974311422b0e83c66136e8ac29141..9920b5b7af2d6913189ac6d0255cea41995e524d 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/jit/declarative_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/jit/declarative_cn.rst @@ -5,8 +5,7 @@ declarative .. py:decorator:: paddle.fluid.dygraph.jit.declarative -本装饰器将函数内的动态图API转化为静态图API。此装饰器自动处理静态图模式下的 -Program和Executor，并将结果作为动态图VarBase返回。 +本装饰器将函数内的动态图API转化为静态图API。此装饰器自动处理静态图模式下的Program和Executor，并将结果作为动态图Tensor返回。输出的动态图Tensor可以继续进行动态图训练、预测或其他运算。如果被装饰的函数里面调用其他动态图函数，被调用的函数也会被转化为静态图函数。 **示例代码** @@ -16,6 +15,8 @@ Program和Executor，并将结果作为动态图VarBase返回。 import numpy as np from paddle.fluid.dygraph.jit import declarative + fluid.enable_dygraph() + @declarative def func(x): x = fluid.dygraph.to_variable(x) diff --git a/doc/paddle/api/paddle/fluid/dygraph/layers/Layer_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/layers/Layer_cn.rst index ffb30530b8d7a51170deeadb48e843c80ea1c719..ffce7959f30a98d46783db09b3c4f8b0a657777b 100644 --- a/doc/paddle/api/paddle/fluid/dygraph/layers/Layer_cn.rst +++ b/doc/paddle/api/paddle/fluid/dygraph/layers/Layer_cn.rst @@ -391,14 +391,13 @@ buffer是一个非参数类型的变量，不会被优化器更新，但在评 state_dict = emb.state_dict() fluid.save_dygraph(state_dict, "paddle_dy") -.. py:method:: set_state_dict(state_dict, include_sublayers=True, use_structured_name=True) +.. py:method:: set_dict(stat_dict, include_sublayers=True) -根据传入的 ``state_dict`` 设置参数和可持久性buffers。 所有参数和buffers将由 ``state_dict`` 中的 ``Tensor`` 设置。 +根据传入的 ``stat_dict`` 设置参数和可持久性buffers。 所有参数和buffers将由 ``stat_dict`` 中的 ``Tensor`` 设置。 参数： - **state_dict** (dict) - 包含所有参数和可持久性buffers的dict。 - **include_sublayers** (bool, 可选) - 如果设置为True，则还包括子层的参数和buffers。 默认值：True。 - - **use_structured_name** (bool, 可选) - 如果设置为True，将使用Layer的结构性变量名作为dict的key，否则将使用Parameter或者Buffer的变量名作为key。默认值：True。 返回：None @@ -406,16 +405,36 @@ buffer是一个非参数类型的变量，不会被优化器更新，但在评 .. code-block:: python - import paddle - - paddle.disable_static() - - emb = paddle.nn.Embedding([10, 10]) + import paddle.fluid as fluid + with fluid.dygraph.guard(): + emb = fluid.dygraph.Embedding([10, 10]) + state_dict = emb.state_dict() + fluid.save_dygraph(state_dict, "paddle_dy") + para_state_dict, _ = fluid.load_dygraph("paddle_dy") + emb.set_dict(para_state_dict) + +.. py:method:: load_dict(stat_dict, include_sublayers=True) + +.. warning:: + 该函数将被弃用。请使用set_dict函数。 + +根据传入的 ``stat_dict`` 设置参数和可持久性buffers。 所有参数和buffers将由 ``stat_dict`` 中的 ``Tensor`` 设置。 + +参数： + - **state_dict** (dict) - 包含所有参数和可持久性buffers的dict。 + - **include_sublayers** (bool, 可选) - 如果设置为True，则还包括子层的参数和buffers。 默认值：True。 + +返回：None - state_dict = emb.state_dict() - paddle.save(state_dict, "paddle_dy") - - para_state_dict, _ = paddle.load("paddle_dy") +**代码示例** + +.. code-block:: python - emb.set_state_dict(para_state_dict) + import paddle.fluid as fluid + with fluid.dygraph.guard(): + emb = fluid.dygraph.Embedding([10, 10]) + state_dict = emb.state_dict() + fluid.save_dygraph(state_dict, "paddle_dy") + para_state_dict, _ = fluid.load_dygraph("paddle_dy") + emb.load_dict(para_state_dict) diff --git a/doc/paddle/api/paddle/fluid/dygraph/parallel/DataParallel_cn.rst b/doc/paddle/api/paddle/fluid/dygraph/parallel/DataParallel_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..0258a6136d02cbcc5f822fbc7f5d066136cf2d27 --- /dev/null +++ b/doc/paddle/api/paddle/fluid/dygraph/parallel/DataParallel_cn.rst @@ -0,0 +1,208 @@ +.. _cn_api_fluid_dygraph_DataParallel: + +DataParallel +------------ + +.. py:class:: paddle.fluid.dygraph.DataParallel(layers, strategy) + +:api_attr: 命令式编程模式（动态图) + +通过数据并行模式执行动态图模型。 + +目前，``DataParallel`` 仅支持以多进程的方式执行动态图模型。 + +支持两种使用方式： + +1. 使用 ``paddle.distributed.spawn`` 方法启动，例如： + + ``python demo.py`` (spawn need to be called in ``__main__`` method) + +2. 使用 ``paddle.distributed.launch`` 方法启动，例如： + +``python -m paddle.distributed.launch –selected_gpus=0,1 demo.py`` + +其中 ``demo.py`` 脚本的代码可以是下面的示例代码。 + +参数： + - **Layer** (Layer) - 需要通过数据并行方式执行的模型。 + - **strategy** (ParallelStrategy，可选) - (deprecated) 数据并行的策略，包括并行执行的环境配置。默认为None。 + +返回：支持数据并行的 ``Layer`` + +返回类型：Layer实例 + +**代码示例**： + +.. code-block:: python + + import paddle + import paddle.nn as nn + import paddle.optimizer as opt + import paddle.distributed as dist + + class LinearNet(nn.Layer): + def __init__(self): + super(LinearNet, self).__init__() + self._linear1 = nn.Linear(10, 10) + self._linear2 = nn.Linear(10, 1) + + def forward(self, x): + return self._linear2(self._linear1(x)) + + def train(): + # 1. enable dynamic mode + paddle.disable_static() + + # 2. initialize parallel environment + dist.init_parallel_env() + + # 3. create data parallel layer & optimizer + layer = LinearNet() + dp_layer = paddle.DataParallel(layer) + + loss_fn = nn.MSELoss() + adam = opt.Adam( + learning_rate=0.001, parameters=dp_layer.parameters()) + + # 4. run layer + inputs = paddle.randn([10, 10], 'float32') + outputs = dp_layer(inputs) + labels = paddle.randn([10, 1], 'float32') + loss = loss_fn(outputs, labels) + + loss = dp_layer.scale_loss(loss) + loss.backward() + dp_layer.apply_collective_grads() + + adam.step() + adam.clear_grad() + + if __name__ == '__main__': + # 1. start by ``paddle.distributed.spawn`` (default) + dist.spawn(train, nprocs=2) + # 2. start by ``paddle.distributed.launch`` + # train() + +.. py:method:: scale_loss(loss) + +缩放模型损失值 ``loss`` 。在数据并行模式中，损失值 ``loss`` 需要根据并行训练进程的数目进行缩放。 + +如果不在数据并行模式下，会直接返回原 ``loss`` 。 + +参数： + - **loss** (Variable) - 当前模型的损失值。 + +返回：缩放后的损失值 ``loss`` + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import paddle.optimizer as opt + import paddle.distributed as dist + + class LinearNet(nn.Layer): + def __init__(self): + super(LinearNet, self).__init__() + self._linear1 = nn.Linear(10, 10) + self._linear2 = nn.Linear(10, 1) + + def forward(self, x): + return self._linear2(self._linear1(x)) + + def train(): + # 1. enable dynamic mode + paddle.disable_static() + + # 2. initialize parallel environment + dist.init_parallel_env() + + # 3. create data parallel layer & optimizer + layer = LinearNet() + dp_layer = paddle.DataParallel(layer) + + loss_fn = nn.MSELoss() + adam = opt.Adam( + learning_rate=0.001, parameters=dp_layer.parameters()) + + # 4. run layer + inputs = paddle.randn([10, 10], 'float32') + outputs = dp_layer(inputs) + labels = paddle.randn([10, 1], 'float32') + loss = loss_fn(outputs, labels) + + loss = dp_layer.scale_loss(loss) + loss.backward() + dp_layer.apply_collective_grads() + + adam.step() + adam.clear_grad() + + if __name__ == '__main__': + # 1. start by ``paddle.distributed.spawn`` (default) + dist.spawn(train, nprocs=2) + # 2. start by ``paddle.distributed.launch`` + # train() + + +.. py:method:: apply_collective_grads() + +AllReduce（规约）参数的梯度值。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import paddle.optimizer as opt + import paddle.distributed as dist + + class LinearNet(nn.Layer): + def __init__(self): + super(LinearNet, self).__init__() + self._linear1 = nn.Linear(10, 10) + self._linear2 = nn.Linear(10, 1) + + def forward(self, x): + return self._linear2(self._linear1(x)) + + def train(): + # 1. enable dynamic mode + paddle.disable_static() + + # 2. initialize parallel environment + dist.init_parallel_env() + + # 3. create data parallel layer & optimizer + layer = LinearNet() + dp_layer = paddle.DataParallel(layer) + + loss_fn = nn.MSELoss() + adam = opt.Adam( + learning_rate=0.001, parameters=dp_layer.parameters()) + + # 4. run layer + inputs = paddle.randn([10, 10], 'float32') + outputs = dp_layer(inputs) + labels = paddle.randn([10, 1], 'float32') + loss = loss_fn(outputs, labels) + + loss = dp_layer.scale_loss(loss) + loss.backward() + dp_layer.apply_collective_grads() + + adam.step() + adam.clear_grad() + + if __name__ == '__main__': + # 1. start by ``paddle.distributed.spawn`` (default) + dist.spawn(train, nprocs=2) + # 2. start by ``paddle.distributed.launch`` + # train() diff --git a/doc/paddle/api/paddle/fluid/executor/global_scope_cn.rst b/doc/paddle/api/paddle/fluid/executor/global_scope_cn.rst index 86031eedc8c1c8f8fc9083054b189194dba6a009..277bb23db092c0b44704ac5905a968f364d3bc7b 100644 --- a/doc/paddle/api/paddle/fluid/executor/global_scope_cn.rst +++ b/doc/paddle/api/paddle/fluid/executor/global_scope_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_fluid_global_scope: +.. _cn_api_fluid_executor_global_scope: global_scope ------------------------------- @@ -25,4 +25,4 @@ global_scope fluid.global_scope().var("data").get_tensor().set(numpy.ones((1, 2)), fluid.CPUPlace()) data = numpy.array(fluid.global_scope().find_var("data").get_tensor()) - print(data) # [[1. 1.]] \ No newline at end of file + print(data) # [[1. 1.]] diff --git a/doc/paddle/api/paddle/fluid/executor/scope_guard_cn.rst b/doc/paddle/api/paddle/fluid/executor/scope_guard_cn.rst index df0566e1b7c3e4931bf69e3734773e4a333f4d57..e220cd8d451708031d2526534a686a852ba67807 100644 --- a/doc/paddle/api/paddle/fluid/executor/scope_guard_cn.rst +++ b/doc/paddle/api/paddle/fluid/executor/scope_guard_cn.rst @@ -1,10 +1,10 @@ -.. _cn_api_fluid_scope_guard: +.. _cn_api_fluid_executor_scope_guard: scope_guard ------------------------------- -.. py:function:: paddle.fluid.scope_guard(scope) +.. py:function:: paddle.fluid.executor.scope_guard (scope) :api_attr: 声明式编程模式（静态图) diff --git a/doc/paddle/api/paddle/fluid/framework/Program_cn.rst b/doc/paddle/api/paddle/fluid/framework/Program_cn.rst deleted file mode 100644 index 2a611c7b0e913f8ed6ceb13ad88566c101dc8ef6..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/framework/Program_cn.rst +++ /dev/null @@ -1,450 +0,0 @@ -.. _cn_api_fluid_Program: - -Program -------------------------------- - -.. py:class:: paddle.fluid.Program - - - - -**注意：默认情况下，Paddle Fluid内部默认含有** :ref:`cn_api_fluid_default_startup_program` **和** :ref:`cn_api_fluid_default_main_program` **，它们共享参数。** :ref:`cn_api_fluid_default_startup_program` **只运行一次来初始化参数，** :ref:`cn_api_fluid_default_main_program` **在每个mini batch中运行并更新权重。** - -Program是Paddle Fluid对于计算图的一种静态描述，使用Program的构造函数可以创建一个Program。Program中包括至少一个 :ref:`api_guide_Block` ，当 :ref:`api_guide_Block` 中存在条件选择的控制流OP（例如 :ref:`cn_api_fluid_layers_While` 等）时，该Program将会含有嵌套着的 :ref:`api_guide_Block` 即控制流外部的 :ref:`api_guide_Block` 将包含着控制流内部的 :ref:`api_guide_Block` ，而嵌套的 :ref:`api_guide_Block` 的元素访问控制将由具体的控制流OP来决定。关于Program具体的结构和包含的类型请参阅 `framework.proto `_ -。 - -一个Program的集合通常包含初始化程序（startup_program）与主程序(main_program)，初始化程序是一个包含一些初始化工作的Program，主程序将会包含用来训练的网络结构和变量，在使用同一个 :ref:`api_guide_executor` 执行时他们会共享初始化工作的结果，例如初始化的参数。一个Program的集合可以被用来测试或者训练，被用来训练时， ``Paddle Fluid`` 将会利用所有用户使用的OP和变量来搭建一个训练网络，被用来测试时， 可以通过调用Program相关的接口例如：`clone` 剪去一些与测试无关的OP和变量，比如反向传播的OP和变量。 - - -返回：创建的空的Program - -返回值类型：Program - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - main_program = fluid.Program() - startup_program = fluid.Program() - with fluid.program_guard(main_program=main_program, startup_program=startup_program): - x = fluid.layers.data(name="x", shape=[-1, 784], dtype='float32') - y = fluid.layers.data(name="y", shape=[-1, 1], dtype='int32') - z = fluid.layers.fc(name="fc", input=x, size=10, act="relu") - - # start_up program here will share fc's weight with main program - print("main program is: {}".format(main_program)) - - print("start up program is: {}".format(startup_program)) - - -.. py:method:: to_string(throw_on_error, with_details=False) - -将Program转换为字符串 - -参数： - - **throw_on_error** (bool) - 是否在没有设置必需字段时抛出异常。 - - **with_details** (bool) - 值为true时，打印更多关于变量和参数的信息，如trainable, optimize_attr等 - -返回： 将Program转换为字符串 - -返回类型： str - -抛出异常： ``ValueError`` - 当 ``throw_on_error == true`` ，当没有设置任何必需的字段时，抛出 ``ValueError`` 。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - x = fluid.layers.data(name="X", shape=[2,3], dtype="float32", append_batch_size=False) - pred = fluid.layers.fc(x, size=3) - prog_string = prog.to_string(throw_on_error=True, with_details=False) - prog_string_with_details = prog.to_string(throw_on_error=False, with_details=True) - print("program string without detail: {}".format(prog_string)) - print("program string with detail: {}".format(prog_string_with_details)) - -.. py:method:: clone(for_test=False) - -**注意:** - **1.** ``Program.clone()`` **方法不会克隆例如** :ref:`cn_api_fluid_io_DataLoader` **这样的数据读取相关的部分，这可能会造成的数据读取部分在克隆后丢失** - - **2. 此API当** ``for_test=True`` **时将会裁剪部分OP和变量。为防止错误的裁剪，推荐在** :ref:`cn_api_fluid_backward_append_backward` **和执行优化器之前使用** ``clone(for_test=True)`` 。 - - -当 ``for_test=True`` 时创建一个新的、仅包含当前Program前向内容的Program。否则创建一个新的，和当前Program完全相同的Program - -有些OP，在训练和测试之间的行为是不同的，比如 :ref:`cn_api_fluid_layers_batch_norm` 。它们有一个属性 ``is_test`` 来控制行为。当 ``for_test=True`` 时，此方法将把它们的 ``is_test`` 属性更改为True。 - -- 克隆Program用于训练时，将 ``for_test`` 设置为False。 -- 克隆Program用于测试时，将 ``for_test`` 设置为True。虽然在这种情况下，如果在使用了优化器之后调用 ``clone`` 我们依旧会对Program当中反向执行以及优化器相关的内容进行自动裁剪，但是，我们强烈建议在使用优化器之前使用 ``clone`` 例如如果使用的是 :ref:`cn_api_fluid_optimizer_Momentum` 可以这样去使用: - -**代码示例** - - :: - - import paddle.fluid as fluid - img = fluid.layers.data(name='image', shape=[784]) - pred = fluid.layers.fc(input=img, size=10, act='relu') - loss = fluid.layers.mean(pred) - ## 我们推荐在使用 Optimizer前使用clone()接口 - test_program = fluid.default_main_program().clone(for_test=True) - optimizer = fluid.optimizer.Momentum(learning_rate=0.01, momentum=0.9) - optimizer.minimize(loss) - -参数： - - **for_test** (bool) – 取值为True时，clone方法内部会把operator的属性 ``is_test`` 设置为 True， 并裁剪反向OP和参数优化OP，默认值为False - -返回：当 ``for_test=True`` 时返回一个新的、仅包含当前Program前向内容的Program。否则返回一个新的，和当前Program完全相同的Program - -返回类型： Program - -**代码示例** - -注意，Program在clone后的顺序可能不同，这不会影响的训练或测试进程。在下面的示例中，我们提供了一个简单的方法print_prog（Program）来打印程序描述，以确保clone后仍能得到同样的打印结果： - -.. code-block:: python - - import paddle.fluid as fluid - import six - - - def print_prog(prog): - for name, value in sorted(six.iteritems(prog.block(0).vars)): - print(value) - for op in prog.block(0).ops: - print("op type is {}".format(op.type)) - print("op inputs are {}".format(op.input_arg_names)) - print("op outputs are {}".format(op.output_arg_names)) - for key, value in sorted(six.iteritems(op.all_attrs())): - if key not in ['op_callstack', 'op_role_var']: - print(" [ attrs: {}: {} ]".format(key, value)) - -1.克隆一个Program，示例代码如下。 - -.. code-block:: python - - import paddle.fluid as fluid - import six - - def print_prog(prog): - for name, value in sorted(six.iteritems(prog.block(0).vars)): - print(value) - for op in prog.block(0).ops: - print("op type is {}".format(op.type)) - print("op inputs are {}".format(op.input_arg_names)) - print("op outputs are {}".format(op.output_arg_names)) - for key, value in sorted(six.iteritems(op.all_attrs())): - if key not in ['op_callstack', 'op_role_var']: - print(" [ attrs: {}: {} ]".format(key, value)) - - train_program = fluid.Program() - startup_program = fluid.Program() - - # ``startup_program`` 被用来执行一些参数初始化工作 - # ``main_program`` 被用来容纳网络 - with fluid.program_guard(train_program, startup_program): - with fluid.unique_name.guard(): - img = fluid.layers.data(name='image', shape=[784]) - hidden = fluid.layers.fc(input=img, size=200, act='relu') - hidden = fluid.layers.dropout(hidden, dropout_prob=0.5) - loss = fluid.layers.cross_entropy( - input=fluid.layers.fc(hidden, size=10, act='softmax'), - label=fluid.layers.data(name='label', shape=[1], dtype='int64')) - avg_loss = fluid.layers.mean(loss) - test_program = train_program.clone(for_test=True) - print_prog(test_program) - - # 由于需要使训练和测试参数共享，我们需要使用训练的 ``startup_program`` - # 来代替测试用的 ``startup_program``, 尽管测试的 ``startup_program`` 里面什么也没有。 - - # 在Paddle Fluid中我们会通过同样的变量名来共享权重. - # 训练和测试程序的所有参数将会拥有同样的名字，这将会使训练和测试程序实现参数的共享， - # 所以我们使用训练程序的 ``startup_program`` .并且由于测试的 ``startup_program`` 什么也没有, - # 因此它是一个新的程序. - with fluid.program_guard(train_program, startup_program): - with fluid.unique_name.guard(): - sgd = fluid.optimizer.SGD(learning_rate=1e-3) - sgd.minimize(avg_loss) - -2.如果分别运行 train Program 和 test Program，则可以不使用clone。 - -.. code-block:: python - - import paddle.fluid as fluid - import six - - def print_prog(prog): - for name, value in sorted(six.iteritems(prog.block(0).vars)): - print(value) - for op in prog.block(0).ops: - print("op type is {}".format(op.type)) - print("op inputs are {}".format(op.input_arg_names)) - print("op outputs are {}".format(op.output_arg_names)) - for key, value in sorted(six.iteritems(op.all_attrs())): - if key not in ['op_callstack', 'op_role_var']: - print(" [ attrs: {}: {} ]".format(key, value)) - - def network(): - img = fluid.layers.data(name='image', shape=[784]) - hidden = fluid.layers.fc(input=img, size=200, act='relu') - hidden = fluid.layers.dropout(hidden, dropout_prob=0.5) - loss = fluid.layers.cross_entropy( - input=fluid.layers.fc(hidden, size=10, act='softmax'), - label=fluid.layers.data(name='label', shape=[1], dtype='int64')) - avg_loss = fluid.layers.mean(loss) - return avg_loss - - train_program_2 = fluid.Program() - startup_program_2 = fluid.Program() - test_program_2 = fluid.Program() - with fluid.program_guard(train_program_2, startup_program_2): - with fluid.unique_name.guard(): - avg_loss = network() - sgd = fluid.optimizer.SGD(learning_rate=1e-3) - sgd.minimize(avg_loss) - # 不使用测试阶段的启动程序 - with fluid.program_guard(test_program_2, startup_program_2): - with fluid.unique_name.guard(): - avg_loss = network() - print_prog(test_program_2) - -上边两个代码片段生成和打印的Program是一样的。 - -.. py:staticmethod:: parse_from_string(binary_str) - -通过对 `protobuf `_ 的反序列化，转换成Program - - -参数： - - **binary_str_type** (str) – `protobuf `_ 二进制字符串 - -返回：反序列化后的 Program - -返回类型：Program - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - startup_prog = fluid.Program() - main_prog = fluid.Program() - with fluid.program_guard(startup_prog, main_prog): - x = fluid.layers.data( - name='X', shape=[1000, 784], dtype='float32', append_batch_size=False) - - y = fluid.layers.data( - name='Y', shape=[784, 100], dtype='float32', append_batch_size=False) - - z = fluid.layers.mul(x=x, y=y) - - binary_str = fluid.default_main_program().desc.serialize_to_string() - prog_restored = fluid.default_main_program().parse_from_string(binary_str) - - print(fluid.default_main_program()) - print(prog_restored) - - # 这里打印出的两个Program应该是一模一样的 - -.. py:attribute:: num_blocks - -该Program中的 :ref:`api_guide_Block` 的个数 - -返回： 该Program中的 :ref:`api_guide_Block` 的个数 - -返回类型：int - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - num_blocks = prog.num_blocks - print(num_blocks) - - ## 1 - ## 当前Program中只有一个Block，即全局的Block - -.. py:attribute:: random_seed - -**注意：必须在相关OP被添加之前设置。** - -程序中随机运算符的默认随机种子。0意味着随机生成随机种子。 - -返回：该Program中当前正在使用的random seed - -返回类型：int64 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - random_seed = prog.random_seed - x_var = fluid.layers.data(name="X", shape=[3,3], dtype="float32", append_batch_size=False) - print(random_seed) - ## 0 - ## 默认的random seed是 0 - - # 这里我们必须要在fluid.layers.dropout之前设置random_seed - prog.random_seed = 1 - z_var = fluid.layers.dropout(x_var, 0.7) - - print(prog.random_seed) - ## 1 - ## 修改后random seed变成了 1 - -.. py:method:: global_block() - -获取该Program的第一个 :ref:`api_guide_Block` 。 - -返回：该Program的第一个 :ref:`api_guide_Block` - -返回类型：:ref:`api_guide_Block` - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - gb_block = prog.global_block() - print(gb_block) - ## - ## idx: 0 - ## parent_idx: -1 - ## 打印出了当前全局Block的描述 - -.. py:method:: block(index) - -返回该Program中 ， ``index`` 指定的 :ref:`api_guide_Block` 。 ``index`` 类型为int - -参数: - - **index** (int) - 需要获取的 :ref:`api_guide_Block` 的index - -返回: 该Program中index对应的那个 :ref:`api_guide_Block` - -返回类型: :ref:`api_guide_Block` - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - block_0 = prog.block(0) - print(block_0) - ## - ## idx: 0 - ## parent_idx: -1 - ## 打印出了0号Block的描述 - -.. py:method:: current_block() - -获取当前 :ref:`api_guide_Block` 。当前 :ref:`api_guide_Block` 是用来添加OP的。 - -返回: 该Program中用户当前所在的 :ref:`api_guide_Block` - -返回类型: :ref:`api_guide_Block` - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - current_blk = prog.current_block() - print(current_blk) - ## - ## idx: 0 - ## parent_idx: -1 - ## 打印出了当前Block的描述 - -.. py:method:: list_vars() - -获取当前Program中所有变量。返回值是一个可迭代对象（iterable object)。 - -返回: Generator 会yield每个Program中的变量 - -返回类型: iterable 的 :ref:`api_guide_Variable` - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - prog = fluid.default_main_program() - img = fluid.layers.data(name='img', shape=[1,28,28], dtype='float32') - label = fluid.layers.data(name='label', shape=[128,1], dtype='int64') - for var in prog.list_vars(): - print(var) - - # 这里将会打印出当前Program中所有的Variable - -.. py:method:: all_parameters() - -获取当前Program中所有的 :ref:`api_guide_parameter` 。返回值是一个列表。 - -返回: 一个包含当前Program中所有参数的列表。 - -返回类型: list[ :ref:`api_guide_parameter` ] - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - program = fluid.default_main_program() - data = fluid.data(name='x', shape=[None, 13], dtype='float32') - hidden = fluid.layers.fc(input=data, size=10) - loss = fluid.layers.mean(hidden) - fluid.optimizer.SGD(learning_rate=0.01).minimize(loss) - - for param in program.all_parameters(): - print(param) - - # 这里将会打印出当前Program中所有的Parameters，在本例中，输出结果是: - # - # name: "fc_0.w_0" - # type { - # type: LOD_TENSOR - # lod_tensor { - # tensor { - # data_type: FP32 - # dims: 13 - # dims: 10 - # } - # } - # } - # - # persistable: true - # name: "fc_0.b_0" - # type { - # type: LOD_TENSOR - # lod_tensor { - # tensor { - # data_type: FP32 - # dims: 10 - # } - # } - # } - # persistable: true - # - # 这里print(param)将会打印出一个参数所有的属性，包括name，type和persistable， - # 你可以访问一个参数的指定属性，例如param.name，param.type \ No newline at end of file diff --git a/doc/paddle/api/paddle/fluid/framework/Variable_cn.rst b/doc/paddle/api/paddle/fluid/framework/Variable_cn.rst index 4abe3040d20cc7dc223e7d0b1f3610e6fd87ea89..83af840cce8702bc2af188a1cab30f3561049d98 100644 --- a/doc/paddle/api/paddle/fluid/framework/Variable_cn.rst +++ b/doc/paddle/api/paddle/fluid/framework/Variable_cn.rst @@ -145,7 +145,7 @@ Variable **参数:** - - **backward_strategy**: ( :ref:`cn_api_fluid_dygraph_BackwardStrategy` ) 使用何种 :ref:`cn_api_fluid_dygraph_BackwardStrategy` 聚合反向的梯度 + - **retain_graph** (bool，可选) – 该参数用于确定反向梯度更新完成后反向梯度计算图是否需要保留（retain_graph为True则保留反向梯度计算图）。若用户打算在执行完该方法（ :code:`backward` ）后，继续向之前已构建的计算图中添加更多的Op，则需要设置 :code:`retain_graph` 值为True（这样才会保留之前计算得到的梯度）。可以看出，将 :code:`retain_graph` 设置为False可降低内存的占用。默认值为False。 返回：无 @@ -153,23 +153,20 @@ Variable **示例代码** .. code-block:: python - import paddle.fluid as fluid import numpy as np - + import paddle + paddle.disable_static() x = np.ones([2, 2], np.float32) - with fluid.dygraph.guard(): - inputs2 = [] - for _ in range(10): - tmp = fluid.dygraph.base.to_variable(x) - # 如果这里我们不为输入tmp设置stop_gradient=False，那么后面loss2也将因为这个链路都不需要梯度 - # 而不产生梯度 - tmp.stop_gradient=False - inputs2.append(tmp) - ret2 = fluid.layers.sums(inputs2) - loss2 = fluid.layers.reduce_sum(ret2) - backward_strategy = fluid.dygraph.BackwardStrategy() - backward_strategy.sort_sum_gradient = True - loss2.backward(backward_strategy) + inputs = [] + for _ in range(10): + tmp = paddle.to_tensor(x) + # 如果这里我们不为输入tmp设置stop_gradient=False，那么后面loss也将因为这个链路都不需要梯度 + # 而不产生梯度 + tmp.stop_gradient=False + inputs.append(tmp) + ret = paddle.sums(inputs) + loss = paddle.reduce_sum(ret) + loss.backward() .. py:method:: gradient() @@ -202,9 +199,7 @@ Variable inputs2.append(tmp) ret2 = fluid.layers.sums(inputs2) loss2 = fluid.layers.reduce_sum(ret2) - backward_strategy = fluid.dygraph.BackwardStrategy() - backward_strategy.sort_sum_gradient = True - loss2.backward(backward_strategy) + loss2.backward() print(loss2.gradient()) # example2: 返回tuple of ndarray @@ -248,9 +243,7 @@ Variable inputs2.append(tmp) ret2 = fluid.layers.sums(inputs2) loss2 = fluid.layers.reduce_sum(ret2) - backward_strategy = fluid.dygraph.BackwardStrategy() - backward_strategy.sort_sum_gradient = True - loss2.backward(backward_strategy) + loss2.backward() print(loss2.gradient()) loss2.clear_gradient() print("After clear {}".format(loss2.gradient())) @@ -351,6 +344,7 @@ Variable .. code-block:: python import paddle.fluid as fluid + import numpy as np with fluid.dygraph.guard(): value0 = np.arange(26).reshape(2, 13).astype("float32") @@ -366,9 +360,9 @@ Variable out1.stop_gradient = True out = fluid.layers.concat(input=[out1, out2, c], axis=1) out.backward() - # 可以发现这里linear的参数变成了 - assert (linear.weight.gradient() == 0).all() - assert (out1.gradient() == 0).all() + # 可以发现这里linear的参数梯度变成了None + assert linear.weight.gradient() is None + assert out1.gradient() is None .. py:attribute:: persistable diff --git a/doc/paddle/api/paddle/fluid/initializer/Normal_cn.rst b/doc/paddle/api/paddle/fluid/initializer/Normal_cn.rst index a7ae0fe063be50f8af93a4197f68c09157a17733..ce50e67bd12563ee7c24b6ab4141acf0ccf0c303 100644 --- a/doc/paddle/api/paddle/fluid/initializer/Normal_cn.rst +++ b/doc/paddle/api/paddle/fluid/initializer/Normal_cn.rst @@ -1,16 +1,115 @@ -.. _cn_api_fluid_initializer_Normal: +.. _cn_api_fluid_layers_Normal: Normal ------------------------------- -.. py:attribute:: paddle.fluid.initializer.Normal +.. py:class:: paddle.fluid.layers.Normal(loc, scale) + + + + +正态分布 + +数学公式： + +.. math:: + + pdf(x; \mu, \sigma) = \frac{1}{Z}e^{\frac {-0.5 (x - \mu)^2} {\sigma^2} } + + Z = (2 \pi \sigma^2)^{0.5} + +上面的数学公式中： + +:math:`loc = \mu` : 平均值。 +:math:`scale = \sigma` : 标准差。 +:math:`Z`: 正态分布常量。 + +参数： + - **loc** (float|list|numpy.ndarray|Variable) - 正态分布平均值。数据类型为float32。 + - **scale** (float|list|numpy.ndarray|Variable) - 正态分布标准差。数据类型为float32。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + from paddle.fluid import layers + from paddle.fluid.layers import Normal + + # 定义参数为float的正态分布。 + dist = Normal(loc=0., scale=3.) + # 定义一组有两个数的正态分布。 + # 第一组为均值1，标准差11，第二组为均值2，标准差22。 + dist = Normal(loc=[1., 2.], scale=[11., 22.]) + # 得到3个样本, 返回一个 3 x 2 张量。 + dist.sample([3]) + + # 通过广播的方式，定义一个两个参数的正态分布。 + # 均值都是1，标准差不同。 + dist = Normal(loc=1., scale=[11., 22.]) + + # 一个完整的例子 + value_npdata = np.array([0.8], dtype="float32") + value_tensor = layers.create_tensor(dtype="float32") + layers.assign(value_npdata, value_tensor) + + normal_a = Normal([0.], [1.]) + normal_b = Normal([0.5], [2.]) + + sample = normal_a.sample([2]) + # 一个由定义好的正太分布随机生成的张量，维度为: [2, 1] + entropy = normal_a.entropy() + # [1.4189385] with shape: [1] + lp = normal_a.log_prob(value_tensor) + # [-1.2389386] with shape: [1] + kl = normal_a.kl_divergence(normal_b) + # [0.34939718] with shape: [1] + + +.. py:function:: sample(shape, seed=0) + +生成指定维度的样本 + +参数： + - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。 + - **seed** (int) - 长整型数。 + +返回：预先设计好维度的张量, 数据类型为float32 + +返回类型：Variable + +.. py:function:: entropy() + +信息熵 + +返回：正态分布的信息熵, 数据类型为float32 + +返回类型：Variable + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Variable) - 输入张量。数据类型为float32或float64。 + +返回：对数概率, 数据类型与value相同 + +返回类型：Variable + +.. py:function:: kl_divergence(other) + +两个正态分布之间的KL散度。 + +参数： + - **other** (Normal) - Normal的实例。 + +返回：两个正态分布之间的KL散度, 数据类型为float32 + +返回类型：Variable -:alias_main: paddle.nn.initializer.Normal -:alias: paddle.nn.initializer.Normal -:old_api: paddle.fluid.initializer.Normal -``NormalInitializer`` 的别名 diff --git a/doc/paddle/api/paddle/fluid/initializer/Uniform_cn.rst b/doc/paddle/api/paddle/fluid/initializer/Uniform_cn.rst index 48a7efeeeddd34a99effca7c37e1c8dea99bf761..59e1544b3751afacf4002cfa859a6827df1de187 100644 --- a/doc/paddle/api/paddle/fluid/initializer/Uniform_cn.rst +++ b/doc/paddle/api/paddle/fluid/initializer/Uniform_cn.rst @@ -1,17 +1,106 @@ -.. _cn_api_fluid_initializer_Uniform: +.. _cn_api_fluid_layers_Uniform: Uniform ------------------------------- -.. py:attribute:: paddle.fluid.initializer.Uniform +.. py:class:: paddle.fluid.layers.Uniform(low, high) + + + + +均匀分布 + +概率密度函数（pdf）为： + +.. math:: + + pdf(x; a, b) = \frac{1}{Z}, a <=x < b + + Z = b - a + +上面的数学公式中： + +:math:`low = a` 。 +:math:`high = b` 。 +:math:`Z`: 正态分布常量。 + +参数low和high的维度必须能够支持广播。 + +参数： + - **low** (float|list|numpy.ndarray|Variable) - 均匀分布的下边界。数据类型为float32。 + - **high** (float|list|numpy.ndarray|Variable) - 均匀分布的上边界。数据类型为float32。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + from paddle.fluid import layers + from paddle.fluid.layers import Uniform + + # 定义参数为float的均匀分布 + u1 = Uniform(low=3.0, high=4.0) + # 定义参数为list的均匀分布 + u2 = Uniform(low=[1.0, 2.0], + high=[3.0, 4.0]) + # 通过广播的方式，定义一个均匀分布 + u3 = Uniform(low=[[1.0, 2.0], + [3.0, 4.0]], + high=[[1.5, 2.5], + [3.5, 4.5]]) + + # 通过广播的方式，定义一个均匀分布 + u4 = Uniform(low=3.0, high=[5.0, 6.0, 7.0]) + + # 一个完整的例子 + value_npdata = np.array([0.8], dtype="float32") + value_tensor = layers.create_tensor(dtype="float32") + layers.assign(value_npdata, value_tensor) + + uniform = Uniform([0.], [2.]) + + sample = uniform.sample([2]) + # 一个由定义好的均匀分布随机生成的张量，维度为: [2, 1] + entropy = uniform.entropy() + # [0.6931472] with shape: [1] + lp = uniform.log_prob(value_tensor) + # [-0.6931472] with shape: [1] + + +.. py:function:: sample(shape, seed=0) + +生成指定维度的样本 + +参数： + - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。 + - **seed** (int) - 长整型数。 + +返回：预先设计好维度的张量, 数据类型为float32 + +返回类型：Variable + +.. py:function:: entropy() + +信息熵 + +返回：均匀分布的信息熵, 数据类型为float32 + +返回类型：Variable + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Variable) - 输入张量。数据类型为float32或float64。 + +返回：对数概率, 数据类型与value相同 + +返回类型：Variable -:alias_main: paddle.nn.initializer.Uniform -:alias: paddle.nn.initializer.Uniform -:old_api: paddle.fluid.initializer.Uniform -``UniformInitializer`` 的别名 diff --git a/doc/paddle/api/paddle/fluid/input/embedding_cn.rst b/doc/paddle/api/paddle/fluid/input/embedding_cn.rst index ee70bead5caa9abd9db685f1709cae196ced9028..b5ad3607114832a799d763d7d68b05a60d65a55d 100644 --- a/doc/paddle/api/paddle/fluid/input/embedding_cn.rst +++ b/doc/paddle/api/paddle/fluid/input/embedding_cn.rst @@ -1,18 +1,22 @@ -.. _cn_api_fluid_embedding: +.. _cn_api_fluid_layers_embedding: embedding ------------------------------- -.. py:function:: paddle.fluid.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') +.. py:function:: paddle.fluid.layers.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') :api_attr: 声明式编程模式（静态图) -该OP根据input中的id信息从embedding矩阵中查询对应embedding信息，函数会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。 +嵌入层(Embedding Layer) -输出的Tensor的shape是在输入Tensor shape的最后一维后面添加了emb_size的维度。 +**注意：此OP将在未来的版本中被移除！该OP要求输入Tensor shape的最后一维必须为1。推荐使用fluid.** :ref:`cn_api_fluid_embedding` 。 + +该OP根据input中的id信息从embedding矩阵中查询对应embedding信息，并会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。 + +要求input的最后一维必须等于1，输出的Tensor的shape是将输入Tensor shape的最后一维的1替换为emb_size。 注：input中的id必须满足 ``0 =< id < size[0]``，否则程序会抛异常退出。 @@ -22,8 +26,8 @@ embedding Case 1: input是Tensor, 且padding_idx = -1 - input.data = [[1, 3], [2, 4], [4, 127]] - input.shape = [3, 2] + input.data = [[[1], [3]], [[2], [4]], [[4], [127]]] + input.shape = [3, 2, 1] 若size = [128, 16] 输出为Tensor: out.shape = [3, 2, 16] @@ -32,7 +36,7 @@ embedding [[0.345249859, 0.124939536, ..., 0.194353745], [0.945345345, 0.435394634, ..., 0.435345365]], - + [[0.945345345, 0.435394634, ..., 0.435345365], [0.0, 0.0, ..., 0.0 ]]] # padding data 输入的padding_idx小于0，则自动转换为padding_idx = -1 + 128 = 127, 对于输入id为127的词，进行padding处理。 @@ -46,25 +50,25 @@ embedding 若size = [128, 16] 输出为LoDTensor: out.lod = [[2, 3]] - out.shape = [5, 1, 16] - out.data = [[[0.129435295, 0.244512452, ..., 0.436322452]], - [[0.345421456, 0.524563927, ..., 0.144534654]], - [[0.345249859, 0.124939536, ..., 0.194353745]], - [[0.945345345, 0.435394634, ..., 0.435345365]], - [[0.0, 0.0, ..., 0.0 ]]] # padding data + out.shape = [5, 16] + out.data = [[0.129435295, 0.244512452, ..., 0.436322452], + [0.345421456, 0.524563927, ..., 0.144534654], + [0.345249859, 0.124939536, ..., 0.194353745], + [0.945345345, 0.435394634, ..., 0.435345365], + [0.0, 0.0, ..., 0.0 ]] # padding data 输入的padding_idx = 0，则对于输入id为0的词，进行padding处理。 参数： - - **input** (Variable) - 存储id信息的Tensor或LoDTensor，数据类型必须为：int64。input中的id必须满足 ``0 =< id < size[0]`` 。 + - **input** (Variable) - 存储id信息的Tensor或LoDTensor，数据类型必须为：int64，输入的shape最后一维须为1。input中的id必须满足 ``0 =< id < size[0]`` 。 - **size** (tuple|list) - embedding矩阵的维度。必须包含两个元素，第一个元素为vocab_size(词表大小), 第二个为emb_size（embedding层维度）。 - **is_sparse** (bool) - 是否使用稀疏的更新方式，这个参数只会影响反向的梯度更新的性能，sparse更新速度更快，推荐使用稀疏更新的方式。但某些optimizer不支持sparse更新，比如 :ref:`cn_api_fluid_optimizer_AdadeltaOptimizer` 、 :ref:`cn_api_fluid_optimizer_AdamaxOptimizer` 、 :ref:`cn_api_fluid_optimizer_DecayedAdagradOptimizer` 、 :ref:`cn_api_fluid_optimizer_FtrlOptimizer` 、 :ref:`cn_api_fluid_optimizer_LambOptimizer` 、:ref:`cn_api_fluid_optimizer_LarsMomentumOptimizer` ，此时is_sparse必须为False。默认为False。 - **is_distributed** (bool) - 是否使用分布式的方式存储embedding矩阵，仅在多机分布式cpu训练中使用。默认为False。 - - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx 会被改成 vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为none，不作处理，默认为None。 + - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx会被改成vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为None，不作处理，默认为None。 - **param_attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为numpy数据格式，且保证本地词向量的shape和embedding的 ``size`` 参数一致，然后使用 :ref:`cn_api_fluid_initializer_NumpyArrayInitializer` 进行初始化，即可实现加载自定义或预训练的词向量。详细使用方法见代码示例2。 - - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32，float64，默认为float32。 + - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32或float64，默认为float32。 -返回：input映射后embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 +返回：input映射后得到的Embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 返回类型：Variable @@ -73,10 +77,12 @@ embedding .. code-block:: python import paddle.fluid as fluid + import numpy as np + data = fluid.layers.data(name='sequence', shape=[1], dtype='int64', lod_level=1) # 示例 1 - emb_1 = fluid.embedding(input=data, size=[128, 64]) + emb_1 = fluid.layers.embedding(input=data, size=[128, 64]) # 示例 2: 加载用户自定义或预训练的词向量 weight_data = np.random.random(size=(128, 100)) # numpy格式的词向量数据 @@ -85,7 +91,7 @@ embedding learning_rate=0.5, initializer=fluid.initializer.NumpyArrayInitializer(weight_data), trainable=True) - emb_2 = fluid.embedding(input=data, size=(128, 100), param_attr=w_param_attrs, dtype='float32') + emb_2 = fluid.layers.embedding(input=data, size=(128, 100), param_attr=w_param_attrs, dtype='float32') diff --git a/doc/paddle/api/paddle/fluid/io/load_cn.rst b/doc/paddle/api/paddle/fluid/io/load_cn.rst index a12a65fbed8eacfcf1f17246fc3ee3001dd81c70..f001976971c5e84eb93c62fa5a5d77c8f2a9a335 100644 --- a/doc/paddle/api/paddle/fluid/io/load_cn.rst +++ b/doc/paddle/api/paddle/fluid/io/load_cn.rst @@ -1,55 +1,168 @@ -.. _cn_api_fluid_load: +.. _cn_api_fluid_dygraph_jit_load: load -------------------------------- - -.. py:function:: paddle.fluid.load(program, model_path, executor=None, var_list=None) - -:api_attr: 声明式编程模式（静态图) - - - -该接口从Program中过滤出参数和优化器信息，然后从文件中获取相应的值。 - -如果Program和加载的文件之间参数的维度或数据类型不匹配，将引发异常。 - -该函数还可以加载用[save_params，save_persistables，save_vars]接口保存的模型文件。 -当[save_params，save_persistables，save_vars]保存的模型格式为单个大文件时，var_list不能为None。 - -参数: - - **program** ( :ref:`cn_api_fluid_Program` ) – 要加载的Program。 - - **model_path** (str) – 保存Program的目录名称+文件前缀。格式为 ``目录名称/文件前缀`` 。 - - **executor** (Executor, 可选) - 当startup program没有运行时，用于初始化参数的Executor。默认值：None。 - - **var_list** (list, 可选) - 指定加载的变量列表，该参数只在加载旧接口[save_params，save_persistables，save_vars]保存的模型文件时使用。当加载的是多个小文件时，变量列表可以是所有加载文件中变量的子集；当加载的单个大文件时，变量列表必须和加载文件中的变量保持一致。 - -返回: 无 - -**代码示例** - -.. code-block:: python - - # example1 - import paddle.fluid as fluid - - x = fluid.data( name="x", shape=[10, 10], dtype='float32') - y = fluid.layers.fc(x, 10) - z = fluid.layers.fc(y, 10) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - fluid.save(fluid.default_main_program(), "./test_path") - fluid.load(fluid.default_main_program(), "./test_path") - - # example2 - # 注意example1和example2应该分开执行，避免干扰。 - import paddle.fluid as fluid - - x = fluid.data( name="x", shape=[10, 10], dtype='float32') - y = fluid.layers.fc(x, 10) - z = fluid.layers.fc(y, 10) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - fluid.save(fluid.default_main_program(), "./test_path") - fluid.load(fluid.default_main_program(), "./test_path", exe) - +----------------- + +.. py:function:: paddle.fluid.dygraph.jit.load(model_path, configs=None) + +:api_attr: 命令式编程模式（动态图) + +将接口 :ref:`cn_api_fluid_dygraph_jit_save` 或者 :ref:`cn_api_fluid_io_save_inference_model` 存储的模型载入为 :ref:`cn_api_fluid_dygraph_TranslatedLayer` ，用于预测推理或者fine-tune训练。 + +.. note:: + 由于一些历史原因，如果载入的模型是通过 :ref:`cn_api_fluid_io_save_inference_model` 存储的， + 在使用它进行fine-tune训练时会存在一些局限： + 1. 命令式编程模式不支持 ``LoDTensor`` ，所有原先输入变量或者参数依赖于LoD信息的模型暂时无法使用； + 2. 所有存储模型的feed变量都需要被传入 ``Translatedlayer`` 的forward方法； + 3. 原模型变量的 ``stop_gradient`` 信息已丢失且无法准确恢复； + 4. 原模型参数的 ``trainable`` 信息已丢失且无法准确恢复。 + +参数： + - **model_path** (str) - 存储模型的目录。 + - **configs** (SaveLoadConfig, 可选) - 用于指定额外配置选项的 :ref:`cn_api_fluid_dygraph_jit_SaveLoadConfig` 对象。默认为 ``None``。 + +返回：TranslatedLayer - 一个能够执行存储模型的 ``Layer`` 对象。 + +**示例代码** + +1. 载入由接口 :ref:`cn_api_fluid_dygraph_jit_save` 存储的模型进行预测推理及fine-tune训练。 + + .. code-block:: python + + import numpy as np + import paddle.fluid as fluid + from paddle.fluid.dygraph import Linear + from paddle.fluid.dygraph import declarative + BATCH_SIZE = 32 + BATCH_NUM = 20 + def random_batch_reader(): + def _get_random_images_and_labels(image_shape, label_shape): + image = np.random.random(size=image_shape).astype('float32') + label = np.random.random(size=label_shape).astype('int64') + return image, label + def __reader__(): + for _ in range(BATCH_NUM): + batch_image, batch_label = _get_random_images_and_labels( + [BATCH_SIZE, 784], [BATCH_SIZE, 1]) + yield batch_image, batch_label + return __reader__ + class LinearNet(fluid.dygraph.Layer): + def __init__(self, in_size, out_size): + super(LinearNet, self).__init__() + self._linear = Linear(in_size, out_size) + @declarative + def forward(self, x): + return self._linear(x) + # 开启命令式编程模式 + fluid.enable_dygraph() + # 1. 训练存储模型. + # 创建网络 + net = LinearNet(784, 1) + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=net.parameters()) + # 创建DataLoader + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + # 训练 + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = net(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + net.clear_gradients() + model_path = "linear.example.model" + fluid.dygraph.jit.save( + layer=net, + model_path=model_path, + input_spec=[img]) + # 2. 载入模型 & 预测 + # 载入模型 + infer_net = fluid.dygraph.jit.load(model_path) + # 预测 + x = fluid.dygraph.to_variable(np.random.random((1, 784)).astype('float32')) + pred = infer_net(x) + # 3. 载入模型 & fine-tune训练 + # 载入模型 + train_net = fluid.dygraph.jit.load(model_path) + train_net.train() + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=train_net.parameters()) + # 创建DataLoader + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + # fine-tune训练 + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = train_net(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + train_net.clear_gradients() + + +2. 载入由接口 :ref:`cn_api_fluid_io_save_inference_model` 存储的模型进行预测推理及fine-tune训练。 + + .. code-block:: python + + import numpy as np + import paddle.fluid as fluid + BATCH_SIZE = 32 + BATCH_NUM = 20 + def random_batch_reader(): + def _get_random_images_and_labels(image_shape, label_shape): + image = np.random.random(size=image_shape).astype('float32') + label = np.random.random(size=label_shape).astype('int64') + return image, label + def __reader__(): + for _ in range(BATCH_NUM): + batch_image, batch_label = _get_random_images_and_labels( + [BATCH_SIZE, 784], [BATCH_SIZE, 1]) + yield batch_image, batch_label + return __reader__ + img = fluid.data(name='img', shape=[None, 784], dtype='float32') + label = fluid.data(name='label', shape=[None, 1], dtype='int64') + pred = fluid.layers.fc(input=img, size=10, act='softmax') + loss = fluid.layers.cross_entropy(input=pred, label=label) + avg_loss = fluid.layers.mean(loss) + optimizer = fluid.optimizer.SGD(learning_rate=0.001) + optimizer.minimize(avg_loss) + place = fluid.CPUPlace() + exe = fluid.Executor(place) + exe.run(fluid.default_startup_program()) + loader = fluid.io.DataLoader.from_generator( + feed_list=[img, label], capacity=5, iterable=True) + loader.set_batch_generator(random_batch_reader(), places=place) + # 1. 训练 & 存储预测模型 + for data in loader(): + exe.run( + fluid.default_main_program(), + feed=data, + fetch_list=[avg_loss]) + model_path = "fc.example.model" + fluid.io.save_inference_model( + model_path, ["img"], [pred], exe) + # 开启命令式编程模式 + fluid.enable_dygraph() + # 2. 载入模型 & 预测 + fc = fluid.dygraph.jit.load(model_path) + x = fluid.dygraph.to_variable(np.random.random((1, 784)).astype('float32')) + pred = fc(x) + # 3. 载入模型 & fine-tune训练 + fc = fluid.dygraph.jit.load(model_path) + fc.train() + sgd = fluid.optimizer.SGD(learning_rate=0.001, + parameter_list=fc.parameters()) + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator( + random_batch_reader(), places=place) + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = fc(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + sgd.minimize(avg_loss) diff --git a/doc/paddle/api/paddle/fluid/layers/BasicDecoder_cn.rst b/doc/paddle/api/paddle/fluid/layers/BasicDecoder_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..dd3820d852961be4903b9e7b6f0f10ca1eac35b8 --- /dev/null +++ b/doc/paddle/api/paddle/fluid/layers/BasicDecoder_cn.rst @@ -0,0 +1,80 @@ +.. _cn_api_fluid_layers_BasicDecoder: + +BasicDecoder +------------------------------- + + +.. py:class:: paddle.fluid.layers.BasicDecoder(cell, helper, output_fn=None) + +BasicDecoder是 :ref:`cn_api_fluid_layers_Decoder` 的子类，它组装了 :ref:`cn_api_fluid_layers_RNNCell` 和 :ref:`cn_api_fluid_layers_DecodeHelper` 的实例作为成员，其中DecodeHelper用来实现不同的解码策略。它依次执行以下步骤来完成单步解码： + +1. 执行 :code:`cell_outputs, cell_states = cell.call(inputs, states)` 以获取输出和新的状态。 + +2. 执行 :code:`sample_ids = helper.sample(time, cell_outputs, cell_states)` 以采样id并将其作为当前步的解码结果。 + +3. 执行 :code:`finished, next_inputs, next_states = helper.next_inputs(time, cell_outputs, cell_states, sample_ids)` 以产生下一解码步的结束标识、输入和状态。 + +参数： + - **cell** (RNNCell) - RNNCell的实例或者具有相同接口定义的对象。 + - **helper** (DecodeHelper) - DecodeHelper的实例。 + - **output_fn** (可选) - 处理cell输出的接口，在采样之前使用。默认值None。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.layers as layers + + start_tokens = fluid.data(name="start_tokens", + shape=[None], + dtype="int64") + + trg_embeder = lambda x: fluid.embedding( + x, size=[10000, 128], param_attr=fluid.ParamAttr(name="trg_embedding")) + output_layer = lambda x: layers.fc(x, + size=10000, + num_flatten_dims=len(x.shape) - 1, + param_attr=fluid.ParamAttr(name= + "output_w"), + bias_attr=False) + helper = layers.SampleEmbeddingHelper(trg_embeder, start_tokens=start_tokens, end_token=1) + decoder_cell = layers.GRUCell(hidden_size=128) + decoder = layers.BasicDecoder(decoder_cell, helper, output_fn=output_layer) + outputs = layers.dynamic_decode( + decoder=decoder, inits=decoder_cell.get_initial_states(start_tokens)) + +.. py:method:: initialize(initial_cell_states) + +初始化，包括helper的初始化和cell的初始化，cell初始化直接使用 :code:`initial_cell_states` 作为结果。 + +参数： + - **initial_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。这是由调用者 :ref:`cn_api_fluid_layers_dynamic_decode` 提供的参数。 + +返回：:code:`(initial_inputs, initial_states, finished)` 的三元组。 :code:`initial_inputs, initial_states` 均是单个tensor变量或tensor变量组成的嵌套结构， :code:`finished` 是bool类型的tensor。 :code:`initial_inputs, finished` 与 :code:`helper.initialize()` 返回的内容相同； :code:`initial_states` 与输入参数中的 :code:`initial_cell_states` 的相同。 + +返回类型：tuple + +.. py:class:: OutputWrapper(cell_outputs, sample_ids) + + :code:`step()` 的返回值中 :code:`outputs` 使用的数据结构，是一个由 :code:`cell_outputs` 和 :code:`sample_ids` 这两个字段构成的命名元组。 + +.. py:method:: step(time, inputs, states, **kwargs) + +按照以下步骤执行单步解码： + +1. 执行 :code:`cell_outputs, cell_states = cell.call(inputs, states)` 以获取输出和新的状态。 + +2. 执行 :code:`sample_ids = helper.sample(time, cell_outputs, cell_states)` 以采样id并将其作为当前步的解码结果。 + +3. 执行 :code:`finished, next_inputs, next_states = helper.next_inputs(time, cell_outputs, cell_states, sample_ids)` 以产生下一解码步的结束标识、输入和状态。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **inputs** (Variable) - tensor变量。在第一个解码时间步时与由 :code:`initialize()` 返回的 :code:`initial_inputs` 相同，其他时间步与由 :code:`step()` 返回的 :code:`next_inputs` 相同。 + - **states** (Variable) - tensor变量的结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`next_states` 相同。 + - **kwargs** - 附加的关键字参数，由调用者 :ref:`cn_api_fluid_layers_dynamic_decode` 提供。 + +返回： :code:`(outputs, next_states, next_inputs, finished)` 的四元组。 :code:`outputs` 是包含 :code:`cell_outputs` 和 :code:`sample_ids` 两个字段的命名元组，其中 :code:`cell_outputs` 是 :code:`cell.call()` 的结果， :code:`sample_ids` 是 :code:`helper.sample()` 的结果； :code:`next_states, next_inputs` 分别和输入参数中的 :code:`states, inputs` 有相同的的结构、形状和数据类型； :code:`finished` 是一个bool类型的tensor，形状是 :math:`[batch\_size]` 。 + +返回类型：tuple diff --git a/doc/paddle/api/paddle/fluid/layers/DecodeHelper_cn.rst b/doc/paddle/api/paddle/fluid/layers/DecodeHelper_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..14ad49c37982245c138bb04b7377d9b40edc6fa1 --- /dev/null +++ b/doc/paddle/api/paddle/fluid/layers/DecodeHelper_cn.rst @@ -0,0 +1,44 @@ +.. _cn_api_fluid_layers_DecodeHelper: + +DecodeHelper +------------------------------- + + +.. py:class:: paddle.fluid.layers.DecodeHelper() + +DecodeHelper是一个基类，其子类的实例将在 :ref:`cn_api_fluid_layers_BasicDecoder` 中使用。它提供了在动态解码时采样和产生下一解码步的输入的接口。 + +.. py:method:: initialize() + +初始化以产生第一个解码步的输入和每个序列是否结束的初始标识。这是 :ref:`cn_api_fluid_layers_BasicDecoder` 初始化的一部分。 + +返回：:code:`(initial_inputs, initial_finished)` 的二元组， :code:`initial_inputs` 是单个tensor变量或tensor变量组成的嵌套结构，tensor的形状是 :math:`[batch\_size, ...]` 。 :code:`initial_finished` 是一个bool类型且形状为 :math:`[batch\_size]` 的tensor。 + +返回类型：tuple + +.. py:method:: sample(time, outputs, states) + +根据 :code:`outputs` 以特定的方式进行采样，该方法是 :code:`BasicDecoder.step` 中的一部分。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + +返回：数据类型为int64形状为 :math:`[batch\_size]` 的tensor，表示采样得到的id。 + +返回类型：Variable + +.. py:method:: next_inputs(time, outputs, states, sample_ids) + +产生下一解码步的输入、状态，以及每个序列是否结束的标识。该方法是 :code:`BasicDecoder.step` 中的一部分。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + - **sample_ids** (Variable) - 数据类型为int64形状为 :math:`[batch\_size]` 的tensor，和由 :code:`sample()` 返回的 :code:`sample_ids` 是同一内容。 + +返回： :code:`(finished, next_inputs, next_states)` 的三元组。 :code:`next_inputs, next_states` 均是单个tensor变量或tensor变量组成的嵌套结构， :code:`next_states` 和输入参数中的 :code:`states` 具有相同的结构、形状和数据类型； :code:`finished` 是一个bool类型且形状为 :math:`[batch\_size]` 的tensor。 + +返回类型：tuple diff --git a/doc/paddle/api/paddle/fluid/layers/Decoder_cn.rst b/doc/paddle/api/paddle/fluid/layers/Decoder_cn.rst index 9adb65614226bafe68094528d902e88ec17d1d83..ffe67dc97342f0ef561d0350c38806ed8bd15ce5 100644 --- a/doc/paddle/api/paddle/fluid/layers/Decoder_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/Decoder_cn.rst @@ -39,13 +39,28 @@ Decoder提供的主要抽象为： 返回类型：tuple -.. py:method:: step(time, inputs, states) +.. py:method:: step(time, inputs, states, **kwargs) 在解码的每个时间步中被调用的接口 参数： - - **outputs** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。 结构和数据类型与 :code:`output_dtype` 相同。 tensor堆叠所有时间步长的输出从而具有shape :math:`[time\_step，batch\_size，...]` ，由调用者完成。 - - **final_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。 它是 :code:`decoder.step` 在最后一个解码步返回的 :code:`next_states`， 因此具有与任何时间步长的状态相同的结构，形状和数据类型。 + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。。 + - **inputs** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。在第一个解码时间步时与由 :code:`initialize()` 返回的 :code:`initial_inputs` 相同，其他时间步与由 :code:`step()` 返回的 :code:`next_inputs` 相同。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`beam_search_state` 相同。 + - **kwargs** - 附加的关键字参数，由调用者提供。 + +返回：一个元组 :code:`(outputs, next_states, next_inputs, finished)` 。:code:`next_states` 和 :code:`next_inputs` 都是单个tensor变量或tensor变量组成的嵌套结构，且结构、形状和数据类型均分别与输入参数中的 :code:`states` 和 :code:`inputs` 相同。 :code:`outputs` 是单个tensor变量或tensor变量组成的嵌套结构。 :code:`finished` 是一个bool类型的tensor变量。 + +返回类型：tuple + +.. py:method:: finalize(self, outputs, final_states, sequence_lengths) + +如果提供了实现，将在整个解码迭代结束后被执行一次。 + +参数： + - **outputs** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。 其中每个tensor的形状均为 :math:`[time\_step，batch\_size，...]` ，是将所有解码步中与其对应的的输出进行堆叠的结果，这个过程由其调用者完成。 + - **final_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。 它是 :code:`decoder.step` 在最后一个解码步返回的 :code:`next_states`， 因此具有与任何时间步的状态相同的结构，形状和数据类型。 + - **kwargs** - 命名关键字参数，由提供调用者。 返回：一个元组 :code:`(final_outputs, final_states)` 。:code:`final_outputs` 和 :code:`final_states` 都是单个tensor变量或tensor变量组成的嵌套结构。 diff --git a/doc/paddle/api/paddle/fluid/layers/GreedyEmbeddingHelper_cn.rst b/doc/paddle/api/paddle/fluid/layers/GreedyEmbeddingHelper_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a01e1ab3e575b54855d774e29057ffc2b7d04a8f --- /dev/null +++ b/doc/paddle/api/paddle/fluid/layers/GreedyEmbeddingHelper_cn.rst @@ -0,0 +1,74 @@ +.. _cn_api_fluid_layers_GreedyEmbeddingHelper: + +GreedyEmbeddingHelper +------------------------------- + + +.. py:class:: paddle.fluid.layers.GreedyEmbeddingHelper(embedding_fn, start_tokens, end_token) + +GreedyEmbeddingHelper是 :ref:`cn_api_fluid_layers_DecodeHelper` 的子类。作为解码helper，它使用 :code:`argmax` 进行采样，并将采样结果送入embedding层，以此作为下一解码步的输入。 + +参数： + - **embedding_fn** (callable) - 作用于 :code:`argmax` 结果的函数，通常是一个将词id转换为词嵌入的embedding层，**注意** ，这里要使用 :ref:`cn_api_fluid_embedding` 而非 :ref:`cn_api_fluid_layers_embedding`，因为选中的id的形状是 :math:`[batch\_size]` ，如果使用后者则还需要在这里提供unsqueeze。 + - **start_tokens** (Variable) - 形状为 :math:`[batch\_size]` 、数据类型为int64、 值为起始标记id的tensor。 + - **end_token** (int) - 结束标记id。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.layers as layers + + start_tokens = fluid.data(name="start_tokens", + shape=[None], + dtype="int64") + + trg_embeder = lambda x: fluid.embedding( + x, size=[10000, 128], param_attr=fluid.ParamAttr(name="trg_embedding")) + output_layer = lambda x: layers.fc(x, + size=10000, + num_flatten_dims=len(x.shape) - 1, + param_attr=fluid.ParamAttr(name= + "output_w"), + bias_attr=False) + helper = layers.GreedyEmbeddingHelper(trg_embeder, start_tokens=start_tokens, end_token=1) + decoder_cell = layers.GRUCell(hidden_size=128) + decoder = layers.BasicDecoder(decoder_cell, helper, output_fn=output_layer) + outputs = layers.dynamic_decode( + decoder=decoder, inits=decoder_cell.get_initial_states(start_tokens)) + +.. py:method:: initialize() + +GreedyEmbeddingHelper初始化，其使用构造函数中的 :code:`start_tokens` 作为第一个解码步的输入，并给出每个序列是否结束的初始标识。这是 :ref:`cn_api_fluid_layers_BasicDecoder` 初始化的一部分。 + +返回：:code:`(initial_inputs, initial_finished)` 的二元组， :code:`initial_inputs` 同构造函数中的 :code:`start_tokens` ； :code:`initial_finished` 是一个bool类型、值为False的tensor，其形状和 :code:`start_tokens` 相同。 + +返回类型：tuple + +.. py:method:: sample(time, outputs, states) + +使用 :code:`argmax` 根据 `outputs` 进行采样。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + +返回：数据类型为int64形状为 :math:`[batch\_size]` 的tensor，表示采样得到的id。 + +返回类型：Variable + +.. py:method:: next_inputs(time, outputs, states, sample_ids) + +对 :code:`sample_ids` 使用 :code:`embedding_fn` ，以此作为下一解码步的输入；同时直接使用输入参数中的 :code:`states` 作为下一解码步的状态；并通过判别 :code:`sample_ids` 是否得到 :code:`end_token`，依此产生每个序列是否结束的标识。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + - **sample_ids** (Variable) - 数据类型为int64形状为 :math:`[batch\_size]` 的tensor，和由 :code:`sample()` 返回的 :code:`sample_ids` 是同一内容。 + +返回： :code:`(finished, next_inputs, next_states)` 的三元组。 :code:`next_inputs, next_states` 均是单个tensor变量或tensor变量组成的嵌套结构，tensor的形状是 :math:`[batch\_size, ...]` ， :code:`next_states` 和输入参数中的 :code:`states` 相同； :code:`finished` 是一个bool类型且形状为 :math:`[batch\_size]` 的tensor。 + +返回类型：tuple diff --git a/doc/paddle/api/paddle/fluid/layers/Normal_cn.rst b/doc/paddle/api/paddle/fluid/layers/Normal_cn.rst index a7ae0fe063be50f8af93a4197f68c09157a17733..ce50e67bd12563ee7c24b6ab4141acf0ccf0c303 100644 --- a/doc/paddle/api/paddle/fluid/layers/Normal_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/Normal_cn.rst @@ -1,16 +1,115 @@ -.. _cn_api_fluid_initializer_Normal: +.. _cn_api_fluid_layers_Normal: Normal ------------------------------- -.. py:attribute:: paddle.fluid.initializer.Normal +.. py:class:: paddle.fluid.layers.Normal(loc, scale) + + + + +正态分布 + +数学公式： + +.. math:: + + pdf(x; \mu, \sigma) = \frac{1}{Z}e^{\frac {-0.5 (x - \mu)^2} {\sigma^2} } + + Z = (2 \pi \sigma^2)^{0.5} + +上面的数学公式中： + +:math:`loc = \mu` : 平均值。 +:math:`scale = \sigma` : 标准差。 +:math:`Z`: 正态分布常量。 + +参数： + - **loc** (float|list|numpy.ndarray|Variable) - 正态分布平均值。数据类型为float32。 + - **scale** (float|list|numpy.ndarray|Variable) - 正态分布标准差。数据类型为float32。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + from paddle.fluid import layers + from paddle.fluid.layers import Normal + + # 定义参数为float的正态分布。 + dist = Normal(loc=0., scale=3.) + # 定义一组有两个数的正态分布。 + # 第一组为均值1，标准差11，第二组为均值2，标准差22。 + dist = Normal(loc=[1., 2.], scale=[11., 22.]) + # 得到3个样本, 返回一个 3 x 2 张量。 + dist.sample([3]) + + # 通过广播的方式，定义一个两个参数的正态分布。 + # 均值都是1，标准差不同。 + dist = Normal(loc=1., scale=[11., 22.]) + + # 一个完整的例子 + value_npdata = np.array([0.8], dtype="float32") + value_tensor = layers.create_tensor(dtype="float32") + layers.assign(value_npdata, value_tensor) + + normal_a = Normal([0.], [1.]) + normal_b = Normal([0.5], [2.]) + + sample = normal_a.sample([2]) + # 一个由定义好的正太分布随机生成的张量，维度为: [2, 1] + entropy = normal_a.entropy() + # [1.4189385] with shape: [1] + lp = normal_a.log_prob(value_tensor) + # [-1.2389386] with shape: [1] + kl = normal_a.kl_divergence(normal_b) + # [0.34939718] with shape: [1] + + +.. py:function:: sample(shape, seed=0) + +生成指定维度的样本 + +参数： + - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。 + - **seed** (int) - 长整型数。 + +返回：预先设计好维度的张量, 数据类型为float32 + +返回类型：Variable + +.. py:function:: entropy() + +信息熵 + +返回：正态分布的信息熵, 数据类型为float32 + +返回类型：Variable + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Variable) - 输入张量。数据类型为float32或float64。 + +返回：对数概率, 数据类型与value相同 + +返回类型：Variable + +.. py:function:: kl_divergence(other) + +两个正态分布之间的KL散度。 + +参数： + - **other** (Normal) - Normal的实例。 + +返回：两个正态分布之间的KL散度, 数据类型为float32 + +返回类型：Variable -:alias_main: paddle.nn.initializer.Normal -:alias: paddle.nn.initializer.Normal -:old_api: paddle.fluid.initializer.Normal -``NormalInitializer`` 的别名 diff --git a/doc/paddle/api/paddle/fluid/layers/RNNCell_cn.rst b/doc/paddle/api/paddle/fluid/layers/RNNCell_cn.rst index edc8d0df0369029d9c9021621919b7a60b1b7523..1368e2ac33f57a483ced44c49ccf65aa83671f7a 100644 --- a/doc/paddle/api/paddle/fluid/layers/RNNCell_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/RNNCell_cn.rst @@ -21,11 +21,11 @@ RNNCell是抽象的基类，代表将输入和状态映射到输出和新状态 - **states** - 状态，单个tensor变量或tensor变量组成的嵌套结构。 - **kwargs** - 附加的关键字参数，由调用者提供。          -返回：输出和新状态。输出和新状态都可以是嵌套的tensor变量。新状态必须具有与状态相同的结构。 +返回：包含输出和新状态的二元组 :code:`(outputs，new_states)` 。输出和新状态都可以是嵌套的tensor变量。新状态必须具有与状态相同的结构。 返回类型：tuple -.. py:method:: get_initial_states(batch_ref, shape=None, dtype=None, init_value=0) +.. py:method:: get_initial_states(batch_ref, shape=None, dtype=None, init_value=0, batch_dim_idx=0) 该接口根据提供的形状，数据类型和初始值来初始化状态。 @@ -34,6 +34,7 @@ RNNCell是抽象的基类，代表将输入和状态映射到输出和新状态 - **shape** - 单个形状或形状组成的嵌套结构，单个形状是整数的列表或元组。 如果形状的第一维不是batch大小，则自动插入-1作为batch大小。 如果该项为None，将使用属性 :code:`state_shape`。默认值为None。 - **dtype** - 单个数据类型或由数据类型组成的嵌套结构。该结构必须与shape的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 如果是None并且属性 :code:`cell.state_shape` 不可用，则float32将用作数据类型。 默认值为None。 - **init_value** - 用于初始化状态的浮点值。 + - **batch_dim_idx** - 用于指示 :code:`batch_ref` 中batch所在维度的int值，默认值为0。 返回：和shape具有相同结构的tensor变量，代表初始状态。 @@ -41,9 +42,9 @@ RNNCell是抽象的基类，代表将输入和状态映射到输出和新状态 .. py:method:: state_shape() -该接口用于初始化cell的状态。 单个形状或由形状组成的嵌套结构，单个形状可以是整数的列表或元组(如果形状的第一维不是batch大小，则自动插入-1作为batch大小)。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`shape` 参数的时候，不用实现该方法。 +抽象方法（属性），该接口用于初始化cell的状态。 单个形状或由形状组成的嵌套结构，单个形状可以是整数的列表或元组(如果形状的第一维不是batch大小，则自动插入-1作为batch大小)。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`shape` 参数的时候，不用实现该方法。 .. py:method:: state_dtype() -该接口用于初始化cell的状态。 单个数据类型或由数据类型组成的嵌套结构，该结构必须与 :code:`shape` 的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`dtype` 参数的时候，不用实现该方法。 +抽象方法（属性），该接口用于初始化cell的状态。 单个数据类型或由数据类型组成的嵌套结构，该结构必须与 :code:`shape` 的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`dtype` 参数的时候，不用实现该方法。 diff --git a/doc/paddle/api/paddle/fluid/layers/SampleEmbeddingHelper_cn.rst b/doc/paddle/api/paddle/fluid/layers/SampleEmbeddingHelper_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c38b80052fe9040d84d3ed3ba353e6e02cfe5a9c --- /dev/null +++ b/doc/paddle/api/paddle/fluid/layers/SampleEmbeddingHelper_cn.rst @@ -0,0 +1,54 @@ +.. _cn_api_fluid_layers_SampleEmbeddingHelper: + +SampleEmbeddingHelper +------------------------------- + + +.. py:class:: paddle.fluid.layers.SampleEmbeddingHelper(embedding_fn, start_tokens, end_token, softmax_temperature=None, seed=None) + +SampleEmbeddingHelper是 :ref:`cn_api_fluid_layers_GreedyEmbeddingHelper` 的子类。作为解码helper，它通过采样而非使用 :code:`argmax` 并将采样结果送入embedding层，以此作为下一解码步的输入。 + +参数： + - **embedding_fn** (callable) - 作用于 :code:`argmax` 结果的函数，通常是一个将词id转换为词嵌入的embedding层，**注意** ，这里要使用 :ref:`cn_api_fluid_embedding` 而非 :ref:`cn_api_fluid_layers_embedding`，因为选中的id的形状是 :math:`[batch\_size]` ，如果使用后者则还需要在这里提供unsqueeze。 + - **start_tokens** (Variable) - 形状为 :math:`[batch\_size]` 、数据类型为int64、 值为起始标记id的tensor。 + - **end_token** (int) - 结束标记id。 + - **softmax_temperature** (float，可选) - 该值用于在softmax计算前除以logits。温度越高（大于1.0）随机性越大，温度越低则越趋向于argmax。该值必须大于0，默认值None等同于1.0。 + - **seed** (int，可选) - 采样使用的随机种子。默认为None，表示不使用固定的随机种子。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.layers as layers + + start_tokens = fluid.data(name="start_tokens", + shape=[None], + dtype="int64") + + trg_embeder = lambda x: fluid.embedding( + x, size=[10000, 128], param_attr=fluid.ParamAttr(name="trg_embedding")) + output_layer = lambda x: layers.fc(x, + size=10000, + num_flatten_dims=len(x.shape) - 1, + param_attr=fluid.ParamAttr(name= + "output_w"), + bias_attr=False) + helper = layers.SampleEmbeddingHelper(trg_embeder, start_tokens=start_tokens, end_token=1) + decoder_cell = layers.GRUCell(hidden_size=128) + decoder = layers.BasicDecoder(decoder_cell, helper, output_fn=output_layer) + outputs = layers.dynamic_decode( + decoder=decoder, inits=decoder_cell.get_initial_states(start_tokens)) + +.. py:method:: sample(time, outputs, states) + +根据一个多项分布进行采样，此分布由 :code:`softmax(outputs/softmax_temperature)` 计算得到。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + +返回：数据类型为int64形状为 :math:`[batch\_size]` 的tensor，表示采样得到的id。 + +返回类型：Variable diff --git a/doc/paddle/api/paddle/fluid/layers/TrainingHelper_cn.rst b/doc/paddle/api/paddle/fluid/layers/TrainingHelper_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..5d140dbf8ac61370b3a0c7a33a50f56c378e4929 --- /dev/null +++ b/doc/paddle/api/paddle/fluid/layers/TrainingHelper_cn.rst @@ -0,0 +1,70 @@ +.. _cn_api_fluid_layers_TrainingHelper: + +TrainingHelper +------------------------------- + + +.. py:class:: paddle.fluid.layers.TrainingHelper(inputs, sequence_length, time_major=False) + +TrainingHelper是 :ref:`cn_api_fluid_layers_DecodeHelper` 的子类。作为解码helper，它在每个解码时间步通过在完整序列输入 :code:`inputs` 的相应位置切片作为各步的输入，并且使用 :code:`argmax` 根据 :code:`cell.call()` 的输出进行采样。 +由于要求有完整的序列输入 :code:`inputs` ，TrainingHelper主要用于以teach-forcing的方式进行最大似然训练，采样得到的内容通常不会使用。 + +参数： + - **inputs** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。当 :code:`time_major == False` 时，tensor的形状应为 :math:`[batch\_size, sequence\_length, ...]`；当 :code:`time_major == True` 时，tensor的形状应为 :math:`[sequence\_length, batch\_size, ...]`。在解码的每一步都要从中切片取出相应的数据。 + - **sequence_length** (Variable) - 形状为 :math:`[batch\_size]` 的tensor。它存储了 :code:`inputs` 中每个样本的实际长度，可以据此来标识每个解码步中每个样本是否结束。 + - **time_major** (bool，可选) - 指示输入tensor和输出tensor中包含的tensor的数据组织。如果为False，则数据组织为batch为主，形状为 :math:`[batch\_size，sequence\_length，...]`。如果为True，则数据组织为time为主，形状为 :math:`[sequence\_length，batch\_size，...]`。默认值：False。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.layers as layers + trg_emb = fluid.data(name="trg_emb", + shape=[None, None, 128], + dtype="float32") + trg_seq_length = fluid.data(name="trg_seq_length", + shape=[None], + dtype="int64") + helper = layers.TrainingHelper(trg_emb, trg_seq_length) + decoder_cell = layers.GRUCell(hidden_size=128) + decoder = layers.BasicDecoder(decoder_cell, helper) + outputs = layers.dynamic_decode( + decoder, + inits=decoder_cell.get_initial_states(trg_emb), + is_test=False) + +.. py:method:: initialize() + +TrainingHelper初始化，其通过在完整序列输入 :code:`inputs` 中首个时间步的位置上切片，以此作为第一个解码步的输入，并给出每个序列是否结束的初始标识。这是 :ref:`cn_api_fluid_layers_BasicDecoder` 初始化的一部分。 + +返回：:code:`(initial_inputs, initial_finished)` 的二元组， :code:`initial_inputs` 是单个tensor变量或tensor变量组成的嵌套结构，tensor的形状是 :math:`[batch\_size, ...]` 。 :code:`initial_finished` 是一个bool类型且形状为 :math:`[batch\_size]` 的tensor。 + +返回类型：tuple + +.. py:method:: sample(time, outputs, states) + +使用 :code:`argmax` 根据 `outputs` 进行采样。由于使用完整序列中的切片作为下一解码步的输入，采样得到的内容通常不会使用。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + +返回：数据类型为int64形状为 :math:`[batch\_size]` 的tensor，表示采样得到的id。 + +返回类型：Variable + +.. py:method:: next_inputs(time, outputs, states, sample_ids) + +从完整序列输入中当前时间步的位置上切片，以此作为产生下一解码步的输入；同时直接使用输入参数中的 :code:`states` 作为下一解码步的状态；并比较当前时间与每个序列的大小，依此产生每个序列是否结束的标识。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **outputs** (Variable) - tensor变量，通常其数据类型为float32或float64，形状为 :math:`[batch\_size, vocabulary\_size]` ，表示当前解码步预测产生的logit（未归一化的概率），和由 :code:`BasicDecoder.output_fn(BasicDecoder.cell.call())` 返回的 :code:`outputs` 是同一内容。 + - **states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构，和由 :code:`BasicDecoder.cell.call()` 返回的 :code:`new_states` 是同一内容。 + - **sample_ids** (Variable) - 数据类型为int64形状为 :math:`[batch\_size]` 的tensor，和由 :code:`sample()` 返回的 :code:`sample_ids` 是同一内容。 + +返回： :code:`(finished, next_inputs, next_states)` 的三元组。 :code:`next_inputs, next_states` 均是单个tensor变量或tensor变量组成的嵌套结构，tensor的形状是 :math:`[batch\_size, ...]` ， :code:`next_states` 和输入参数中的 :code:`states` 相同； :code:`finished` 是一个bool类型且形状为 :math:`[batch\_size]` 的tensor。 + +返回类型：tuple diff --git a/doc/paddle/api/paddle/fluid/layers/Uniform_cn.rst b/doc/paddle/api/paddle/fluid/layers/Uniform_cn.rst index 48a7efeeeddd34a99effca7c37e1c8dea99bf761..59e1544b3751afacf4002cfa859a6827df1de187 100644 --- a/doc/paddle/api/paddle/fluid/layers/Uniform_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/Uniform_cn.rst @@ -1,17 +1,106 @@ -.. _cn_api_fluid_initializer_Uniform: +.. _cn_api_fluid_layers_Uniform: Uniform ------------------------------- -.. py:attribute:: paddle.fluid.initializer.Uniform +.. py:class:: paddle.fluid.layers.Uniform(low, high) + + + + +均匀分布 + +概率密度函数（pdf）为： + +.. math:: + + pdf(x; a, b) = \frac{1}{Z}, a <=x < b + + Z = b - a + +上面的数学公式中： + +:math:`low = a` 。 +:math:`high = b` 。 +:math:`Z`: 正态分布常量。 + +参数low和high的维度必须能够支持广播。 + +参数： + - **low** (float|list|numpy.ndarray|Variable) - 均匀分布的下边界。数据类型为float32。 + - **high** (float|list|numpy.ndarray|Variable) - 均匀分布的上边界。数据类型为float32。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + from paddle.fluid import layers + from paddle.fluid.layers import Uniform + + # 定义参数为float的均匀分布 + u1 = Uniform(low=3.0, high=4.0) + # 定义参数为list的均匀分布 + u2 = Uniform(low=[1.0, 2.0], + high=[3.0, 4.0]) + # 通过广播的方式，定义一个均匀分布 + u3 = Uniform(low=[[1.0, 2.0], + [3.0, 4.0]], + high=[[1.5, 2.5], + [3.5, 4.5]]) + + # 通过广播的方式，定义一个均匀分布 + u4 = Uniform(low=3.0, high=[5.0, 6.0, 7.0]) + + # 一个完整的例子 + value_npdata = np.array([0.8], dtype="float32") + value_tensor = layers.create_tensor(dtype="float32") + layers.assign(value_npdata, value_tensor) + + uniform = Uniform([0.], [2.]) + + sample = uniform.sample([2]) + # 一个由定义好的均匀分布随机生成的张量，维度为: [2, 1] + entropy = uniform.entropy() + # [0.6931472] with shape: [1] + lp = uniform.log_prob(value_tensor) + # [-0.6931472] with shape: [1] + + +.. py:function:: sample(shape, seed=0) + +生成指定维度的样本 + +参数： + - **shape** (list) - 1维列表，指定生成样本的维度。数据类型为int32。 + - **seed** (int) - 长整型数。 + +返回：预先设计好维度的张量, 数据类型为float32 + +返回类型：Variable + +.. py:function:: entropy() + +信息熵 + +返回：均匀分布的信息熵, 数据类型为float32 + +返回类型：Variable + +.. py:function:: log_prob(value) + +对数概率密度函数 + +参数： + - **value** (Variable) - 输入张量。数据类型为float32或float64。 + +返回：对数概率, 数据类型与value相同 + +返回类型：Variable -:alias_main: paddle.nn.initializer.Uniform -:alias: paddle.nn.initializer.Uniform -:old_api: paddle.fluid.initializer.Uniform -``UniformInitializer`` 的别名 diff --git a/doc/paddle/api/paddle/fluid/layers/abs_cn.rst b/doc/paddle/api/paddle/fluid/layers/abs_cn.rst index cf726de9f97c0bc5c621654cf07ff5787f8c9260..3c0cdf4f06dd720c7c1281ede892b01e2089521c 100644 --- a/doc/paddle/api/paddle/fluid/layers/abs_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/abs_cn.rst @@ -11,23 +11,29 @@ abs -绝对值激活函数。 +绝对值函数。 .. math:: out = |x| 参数: - - **x** (Variable)- 多维Tensor，数据类型为float32或float64。 - - **name** (str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回：表示绝对值结果的Tensor，数据类型与x相同。 +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 -返回类型：Variable +返回类型：Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.abs(data) + import paddle + import numpy as np + + paddle.disable_static() + x_data = np.array([-1, -2, -3, -4]).astype(np.float32) + x = paddle.to_variable(x_data) + res = paddle.abs(x) + print(res.numpy()) + # [1, 2, 3, 4] diff --git a/doc/paddle/api/paddle/fluid/layers/acos_cn.rst b/doc/paddle/api/paddle/fluid/layers/acos_cn.rst index 9185569aa0e9f5329c63bc734e3a96996042584e..dad19ff258cbf0b89b6d45fd86eb7cc69c730636 100644 --- a/doc/paddle/api/paddle/fluid/layers/acos_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/acos_cn.rst @@ -11,29 +11,30 @@ acos -arccosine激活函数。 +arccosine函数。 .. math:: out = cos^{-1}(x) 参数: - - **x(Variable)** - acos的输入Tensor，数据类型为 float32 或 float64 - - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。 -返回： `acos` 的输出Tensor，数据类型与 `x` 相同。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回类型： Variable +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 +返回类型： Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[4]) - # if data is [-0.8183, 0.4912, -0.6444, 0.0371] - result = fluid.layers.acos(data) - # result is [2.5293, 1.0573, 2.2711, 1.5336] - - + import paddle + import numpy as np + paddle.disable_static() + x_data = np.array([-0.8183, 0.4912, -0.6444, 0.0371]).astype(np.float32) + x = paddle.to_variable(x_data) + res = paddle.acos(x) + print(res.numpy()) + # [2.5293, 1.0573, 2.2711, 1.5336] diff --git a/doc/paddle/api/paddle/fluid/layers/asin_cn.rst b/doc/paddle/api/paddle/fluid/layers/asin_cn.rst index 03109d28ec3125c9f1cc5a3e8bd97e63484bde07..16ee357e985a6dce813cf2569685b7cc48351363 100644 --- a/doc/paddle/api/paddle/fluid/layers/asin_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/asin_cn.rst @@ -11,29 +11,29 @@ asin -arcsine激活函数。 +arcsine函数。 .. math:: out = sin^{-1}(x) - 参数: - - **x(Variable)** - asin的输入Tensor，数据类型为 float32 或 float64 - - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64、float16。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回： `asin` 的输出Tensor，数据类型与 `x` 相同。 +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 -返回类型： Variable +返回类型： Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[4]) - # if data is [-0.8183, 0.4912, -0.6444, 0.0371] - result = fluid.layers.asin(data) - # result is [-0.9585, 0.5135, -0.7003, 0.0372] - - + import paddle + import numpy as np + paddle.disable_static() + x_data = np.array([-0.8183, 0.4912, -0.6444, 0.0371]).astype(np.float32) + x = paddle.to_variable(x_data) + res = paddle.asin(x) + print(res.numpy()) + # [-0.9585, 0.5135, -0.7003, 0.0372] diff --git a/doc/paddle/api/paddle/fluid/layers/atan_cn.rst b/doc/paddle/api/paddle/fluid/layers/atan_cn.rst index 1c36f104731560ef4918730b21682497cbd415e2..eec8000171fe3192fa6f4267b7a955bbebff5b9a 100644 --- a/doc/paddle/api/paddle/fluid/layers/atan_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/atan_cn.rst @@ -11,30 +11,29 @@ atan -arctanh激活函数。 +arctangent函数。 .. math:: - out = tanh^{-1}(x) + out = tan^{-1}(x) 参数: - - **x(Variable)** - atan的输入Tensor，数据类型为 float32 或 float64 - - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64、float16。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回： `atan` 的输出Tensor，数据类型与 `x` 相同。 +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 -返回类型： Variable +返回类型： Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[4]) - # if data is [-0.8183, 0.4912, -0.6444, 0.0371] - result = fluid.layers.atan(data) - # result is [-0.6858, 0.4566, -0.5724, 0.0371] - - - - + import paddle + import numpy as np + paddle.disable_static() + x_data = np.array([-0.8183, 0.4912, -0.6444, 0.0371]).astype(np.float32) + x = paddle.to_variable(x_data) + res = paddle.atan(x) + print(res.numpy()) + # [-0.6858, 0.4566, -0.5724, 0.0371] diff --git a/doc/paddle/api/paddle/fluid/layers/ceil_cn.rst b/doc/paddle/api/paddle/fluid/layers/ceil_cn.rst index 27ca3dd547fb43ecf26ce0d499ce39049e2ef1bb..5564c641ecc9b722cc60e3fc85913c941542eb88 100644 --- a/doc/paddle/api/paddle/fluid/layers/ceil_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/ceil_cn.rst @@ -19,24 +19,24 @@ ceil 参数: - - **x** (Variable) - 该OP的输入为多维Tensor。数据类型为float32或float64。 - - **name** (str, 可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为None。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64 、float16。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回： 输出为Tensor，与 ``x`` 维度相同、数据类型相同。 +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 -返回类型： Variable +返回类型： Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - import numpy as np + import paddle + import numpy as np - input_ceil = np.array([[-1.5,6],[1,15.6]]) - with fluid.dygraph.guard(): - x = fluid.dygraph.to_variable(input_ceil) - y = fluid.layers.ceil(x) - print(y.numpy()) - # [[-1. 6.] - # [ 1. 16.]] + paddle.disable_static() + x_data = np.array([[-1.5,6],[1,15.6]]).astype(np.float32) + x = paddle.to_variable(x_data) + res = paddle.ceil(x) + print(res.numpy()) + # [[-1. 6.] + # [ 1. 16.]] diff --git a/doc/paddle/api/paddle/fluid/layers/concat_cn.rst b/doc/paddle/api/paddle/fluid/layers/concat_cn.rst index 46b1b3c3d6b17cdd9eebd5959372756499ede8ff..a0c2ade9178f1842e355cfd3bdb0e667db38cd2d 100644 --- a/doc/paddle/api/paddle/fluid/layers/concat_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/concat_cn.rst @@ -15,13 +15,6 @@ concat 返回：联结后的 ``Tensor`` ，数据类型和 ``input`` 中的Tensor相同。 - -抛出异常： - - ``TypeError``: - 当输入 ``input`` 的类型不是list、tuple或者Tensor的时候。 - - ``TypeError``: - 当输入 ``input`` 的数据类型不是 bool，float16， float32， float64， int32， int64时。 - - ``TypeError``: - 当 ``axis`` 的类型不是int或者Tensor时。当 ``axis`` 是Tensor的时候其数据类型不是int32或者int64时。 - - ``TypeError``: - 当输入 ``input`` 中的Tensor存在数据类型不一致时。 - **代码示例**： .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/layers/cos_cn.rst b/doc/paddle/api/paddle/fluid/layers/cos_cn.rst index 4f31c473c95be1f3b4a46915c505fe29250d11e8..0b0d1cd6b8aeb296e385d5499f6718f40afc6829 100644 --- a/doc/paddle/api/paddle/fluid/layers/cos_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/cos_cn.rst @@ -13,32 +13,31 @@ cos 余弦函数。 +输入范围是 `(-inf, inf)` ， 输出范围是 `[-1,1]`。 + .. math:: out = cos(x) - - 参数: - - **x** (Variable) - 该OP的输入为多维Tensor，数据类型为float32，float64。 - - **name** (str, 可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为None。 - + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64 、float16。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回：输出为Tensor，与 ``x`` 维度相同、数据类型相同。 +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 -返回类型：Variable +返回类型：Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - import numpy as np + import paddle + import numpy as np - input_cos = np.array([[-1,np.pi],[1,15.6]]) - with fluid.dygraph.guard(): - x = fluid.dygraph.to_variable(input_cos) - y = fluid.layers.cos(x) - print(y.numpy()) - # [[ 0.54030231 -1. ] - # [ 0.54030231 -0.99417763]] + paddle.disable_static() + x_data = np.array([[-1,np.pi],[1,15.6]]).astype(np.float32) + x = paddle.to_variable(x_data) + res = paddle.cos(x) + print(res.numpy()) + # [[ 0.54030231 -1. ] + # [ 0.54030231 -0.99417763]] diff --git a/doc/paddle/api/paddle/fluid/layers/crf_decoding_cn.rst b/doc/paddle/api/paddle/fluid/layers/crf_decoding_cn.rst deleted file mode 100644 index ea5fd7eb1e56351474a5a72181b8e58e1929811d..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/crf_decoding_cn.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _cn_api_fluid_layers_crf_decoding: - -crf_decoding -------------------------------- - - -.. py:function:: paddle.fluid.layers.crf_decoding(input, param_attr, label=None, length=None) - -:api_attr: 声明式编程模式（静态图) - - - - - -该层读取由 :ref:`cn_api_fluid_layers_linear_chain_crf` 学习的 emission feature weights（发射状态特征的权重）和 transition feature weights (转移特征的权重) 进行解码。 -本层实现了 Viterbi 算法，可以动态地寻找隐藏状态最可能的序列，该序列也被称为 Viterbi 路径（Viterbi path），从而得到观察标签 (tags) 序列。 - -这个层运算的结果会随着输入 ``Label`` 的有无而改变： - - 1. ``Label`` 非 None 的情况，在实际训练中时常发生。此时本层会协同 :ref:`cn_api_fluid_layers_chunk_eval` 工作。在 LoDTensor 模式下，本层会返回一行形为 [N X 1] 的向量，在 padding 模式下，返回形状则为 [B x S]，其中值为 0 的部分代表该 label 不适合作为对应结点的标注，值为1的部分则反之。此类型的输出可以直接作为 :ref:`cn_api_fluid_layers_chunk_eval` 算子的输入； - - 2. 当没有 ``Label`` 时，该函数会执行标准解码过程； - -（没有 ``Label`` 时）该运算返回一个形状为 [N X 1] 或 [B x S] 的向量，此处的形状取决于输入是 LoDTensor 还是普通 Tensor，其中元素取值范围为 0 ~ 最大标注个数-1，分别为预测出的标注（tag）所在的索引。 - -参数： - - **input** (Variable) — 一个形为 [N x D] 的 LoDTensor，其中 N 是mini-batch的大小，D是标注（tag) 的总数； 或者形为 [B x S x D] 的普通 Tensor，B 是批次大小，S 是序列最大长度，D 是标注的总数。 该输入是 :ref:`cn_api_fluid_layers_linear_chain_crf`` 的 unscaled emission weight matrix （未标准化的发射权重矩阵）。数据类型为 float32 或者 float64。 - - **param_attr** (ParamAttr，可选) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **label** (Variable，可选) — 形为 [N x 1] 的正确标注（ground truth）（LoDTensor 模式），或者形状为 [B x S]。 有关该参数的更多信息，请详见上述描述。数据类型为 int64。 - - **length** (Variable，可选) — 形状为 [B x 1], 表示输入序列的真实长度。该输入非 None，表示该层工作在 padding 模式下，即 ``input`` 和 ``label`` 都是带 padding 的普通 Tensor。数据类型为 int64。 - -返回：解码结果具体内容根据 ``Label`` 参数是否提供而定，请参照上面的介绍来详细了解。 - -返回类型： Variable - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - images = fluid.layers.data(name='pixel', shape=[784], dtype='float32') - label = fluid.layers.data(name='label', shape=[1], dtype='int32') - hidden = fluid.layers.fc(input=images, size=2) - crf = fluid.layers.linear_chain_crf(input=hidden, label=label, - param_attr=fluid.ParamAttr(name="crfw")) - crf_decode = fluid.layers.crf_decoding(input=hidden, - param_attr=fluid.ParamAttr(name="crfw")) - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/cumsum_cn.rst b/doc/paddle/api/paddle/fluid/layers/cumsum_cn.rst index fd9238e64bd85b90f4a54ced20b6dda1266b4e60..8e6f238b87381651e08b0a0dac4fa441b7605683 100644 --- a/doc/paddle/api/paddle/fluid/layers/cumsum_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/cumsum_cn.rst @@ -5,11 +5,6 @@ cumsum .. py:function:: paddle.fluid.layers.cumsum(x,axis=None,exclusive=None,reverse=None) -:alias_main: paddle.cumsum -:alias: paddle.cumsum,paddle.tensor.cumsum,paddle.tensor.math.cumsum -:old_api: paddle.fluid.layers.cumsum - - 沿给定轴(axis)的元素的累加和。默认结果的第一个元素和输入的第一个元素一致。如果exlusive为True，结果的第一个元素则为0。 diff --git a/doc/paddle/api/paddle/fluid/layers/data_cn.rst b/doc/paddle/api/paddle/fluid/layers/data_cn.rst index f250c9438581e2cddaebe4f72c8adb5c6821cdb9..14a6ab6ea1d94dcdc3586417ef9c85db98783c74 100644 --- a/doc/paddle/api/paddle/fluid/layers/data_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/data_cn.rst @@ -6,10 +6,6 @@ data .. py:function:: paddle.fluid.data(name, shape, dtype='float32', lod_level=0) -:api_attr: 声明式编程模式（静态图) -:alias_main: paddle.nn.data -:alias: paddle.nn.data,paddle.nn.input.data -:old_api: paddle.fluid.data diff --git a/doc/paddle/api/paddle/fluid/layers/dynamic_decode_cn.rst b/doc/paddle/api/paddle/fluid/layers/dynamic_decode_cn.rst deleted file mode 100644 index 6c439a90a54b5df6be64e743aef1d311d3908f15..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/dynamic_decode_cn.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _cn_api_fluid_layers_dynamic_decode: - -dynamic_decode -------------------------------- - - - -.. py:method:: dynamic_decode(decoder, inits=None, max_step_num=None, output_time_major=False, **kwargs): - -:api_attr: 声明式编程模式（静态图) - - - -该接口重复执行 :code:`decoder.step()` 直到 其返回的表示完成状态的Tensor中的值全部为True或解码步骤达到 :code:`max_step_num`。 - -:code:`decode.initialize()` 会在解码循环之前被调用一次。如果 :code:`decoder` 实现了 :code:`finalize` 方法，则 :code:`decoder.finalize()` 在解码循环后将被调用一次。 - -参数: - - **decoder** (Decoder) - 解码器的实例。 - - **inits** (object，可选) - 传递给 :code:`decoder.initialize` 的参数。默认为None。 - - **max_step_num** (int，可选) - 最大步数。如果未提供，解码直到解码过程完成（ :code:`decode.step()` 返回的表示完成状态的Tensor中的值全部为True）。默认为None。 - - **output_time_major** (bool，可选) - 指明最终输出(此方法的第一个返回值)中包含的Tensor的数据布局。如果为False，其将使用batch优先的数据布局, 此时的形状为 :math:`[batch\_size，seq\_len，...]`。如果为True，其将使用time优先的数据布局，此时的形状为 :math:`[seq\_len，batch\_size，...]`。默认值为False。 - - **kwargs** - 其他命名关键字参数。这些参数将传递给 :code:`decoder.step`。 - -返回:一个二元组 :code:`(final_outputs，final_states)`, 其包含了最终的输出和状态，这两者都是Tensor或Tensor的嵌套结构。:code:`final_outputs` 具有与 :code:`decoder.output_dtype` 相同的结构和数据类型， 其中的每个tensor都是对所有解码时间步对应输出的堆叠。 这些tensor也可能会通过 :code:`decoder.finalize` 进行修改。:code:`final_states` 是最后时间步的状态，和 :code:`decoder.initialize` 返回的初始状态具有相同的结构，其中的tensor也具有相同的形状 和数据类型。 - -返回类型：tuple - -**示例代码** - -.. code-block:: python - - import paddle.fluid as fluid - import paddle.fluid.layers as layers - from paddle.fluid.layers import GRUCell, BeamSearchDecoder, dynamic_decode - encoder_output = fluid.data(name="encoder_output", - shape=[-1, 32, 128], - dtype="float32") - trg_embeder = lambda x: fluid.embedding( - x, size=[10000, 128], param_attr=fluid.ParamAttr(name="trg_embedding")) - output_layer = lambda x: layers.fc(x, - size=10000, - num_flatten_dims=len(x.shape) - 1, - param_attr=fluid.ParamAttr(name= - "output_w"), - bias_attr=False) - decoder_cell = GRUCell(hidden_size=128) - decoder = BeamSearchDecoder(decoder_cell, - start_token=0, - end_token=1, - beam_size=4, - embedding_fn=trg_embeder, - output_fn=output_layer) - outputs = dynamic_decode( - decoder=decoder, inits=decoder_cell.get_initial_states(encoder_output)) diff --git a/doc/paddle/api/paddle/fluid/layers/dynamic_gru_cn.rst b/doc/paddle/api/paddle/fluid/layers/dynamic_gru_cn.rst deleted file mode 100644 index 995ac50067ac3dfbf2b0cbbcaaf8ba0a417f8c12..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/dynamic_gru_cn.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _cn_api_fluid_layers_dynamic_gru: - -dynamic_gru -------------------------------- - - -.. py:function:: paddle.fluid.layers.dynamic_gru(input, size, param_attr=None, bias_attr=None, is_reverse=False, gate_activation='sigmoid', candidate_activation='tanh', h_0=None, origin_mode=False) - -:api_attr: 声明式编程模式（静态图) - - - - -**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用StaticRNN（fluid.layers.** :ref:`cn_api_fluid_layers_StaticRNN` **）。** - -该OP用于在完整序列上逐个时间步的进行单层Gated Recurrent Unit（GRU）的计算，单个时间步内GRU的计算支持以下两种计算方式： - -如果origin_mode为True，则使用的运算公式来自论文 -`Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation `_ 。 - -.. math:: - u_t & = act_g(W_{ux}x_{t} + W_{uh}h_{t-1} + b_u)\\ - r_t & = act_g(W_{rx}x_{t} + W_{rh}h_{t-1} + b_r)\\ - \tilde{h_t} & = act_c(W_{cx}x_{t} + W_{ch}(r_t \odot h_{t-1}) + b_c)\\ - h_t & = u_t \odot h_{t-1} + (1-u_t) \odot \tilde{h_t} - - -如果origin_mode为False，则使用的运算公式来自论文 -`Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling `_ 。 - -公式如下: - -.. math:: - u_t & = act_g(W_{ux}x_{t} + W_{uh}h_{t-1} + b_u)\\ - r_t & = act_g(W_{rx}x_{t} + W_{rh}h_{t-1} + b_r)\\ - \tilde{h_t} & = act_c(W_{cx}x_{t} + W_{ch}(r_t \odot h_{t-1}) + b_c)\\ - h_t & = (1-u_t) \odot h_{t-1} + u_t \odot \tilde{h_t} - - -其中， :math:`x_t` 为当前时间步的输入，这个输入并非 ``input``，该OP不包含 :math:`W_{ux}x_{t}, W_{rx}x_{t}, W_{cx}x_{t}` 的计算， **注意** 要在该OP前使用大小为 ``size`` 的3倍的全连接层并将其输出作为 ``input``； -:math:`h_{t-1}` 为前一时间步的隐状态 ``hidden``； :math:`u_t` 、 :math:`r_t` 、 :math:`\tilde{h_t}` 和 :math:`h_t` 分别代表了GRU单元中update gate（更新门）、reset gate（重置门）、candidate hidden（候选隐状态）和隐状态输出; :math:`\odot` 为逐个元素相乘； -:math:`W_{uh}, b_u` 、 :math:`W_{rh}, b_r` 和 :math:`W_{ch}, b_c` 分别代表更新门、重置门和候选隐状态在计算时使用的权重矩阵和偏置。在实现上，三个权重矩阵合并为一个 :math:`[D, D \times 3]` 形状的Tensor存放，三个偏置拼接为一个 :math:`[1, D \times 3]` 形状的Tensor存放，其中 :math:`D` 为隐单元的数目；权重Tensor存放布局为： :math:`W_{uh}` 和 :math:`W_{rh}` 拼接为 :math:`[D, D \times 2]` 形状位于前半部分，:math:`W_{ch}` 以 :math:`[D, D]` 形状位于后半部分。 - - -参数: - - **input** (Variable) – LoD level为1的LoDTensor，表示经线性变换后的序列输入，形状为 :math:`[T, D \times 3]` ，其中 :math:`T` 表示mini-batch中所有序列长度之和， :math:`D` 为隐状态特征维度的大小。数据类型为float32或float64。 - - **size** (int) – 隐状态特征维度的大小 - - **param_attr** (ParamAttr，可选) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **is_reverse** (bool，可选) – 指明是否按照和输入相反的序列顺序计算，默认为False。 - - **gate_activation** (str，可选) – 公式中 :math:`act_g` 激活函数的类型。支持identity、sigmoid、tanh、relu四种激活函数类型，默认为sigmoid。 - - **candidate_activation** (str，可选) – 公式中 :math:`act_c` 激活函数的类型。支持identity、sigmoid、tanh、relu四种激活函数类型，默认为tanh。 - - **h_0** (Variable，可选) – 表示初始隐状态的Tensor，若未提供，则默认为0。其形状为 :math:`[N, D]` , 其中 :math:`N` 为输入mini-batch中序列的数目， :math:`D` 为隐状态特征维度的大小。数据类型与 ``input`` 相同。默认值为None。 - - **origin_mode** (bool，可选) – 指明要使用的GRU计算方式，两种计算方式具体差异见公式描述，默认值为False。 - -返回： 形状为 :math:`[T, D]` 、LoD level为1的LoDTensor，其中 :math:`T` 表示mini-batch中所有序列长度之和， :math:`D` 为隐状态特征维度的大小。表示经过GRU变换的输出特征序列，和 ``input`` 具有相同的LoD（序列长度）和数据类型。 - -返回类型: Variable - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - dict_dim, emb_dim = 128, 64 - data = fluid.data(name='sequence', - shape=[None], - dtype='int64', - lod_level=1) - emb = fluid.embedding(input=data, size=[dict_dim, emb_dim]) - hidden_dim = 512 - x = fluid.layers.fc(input=emb, size=hidden_dim * 3) - hidden = fluid.layers.dynamic_gru(input=x, size=hidden_dim) - - - - - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/dynamic_lstm_cn.rst b/doc/paddle/api/paddle/fluid/layers/dynamic_lstm_cn.rst deleted file mode 100644 index 5c6bc406ba23f5d80dcf6586a9b32ead36019b72..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/dynamic_lstm_cn.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. _cn_api_fluid_layers_dynamic_lstm: - -dynamic_lstm -------------------------------- - - -.. py:function:: paddle.fluid.layers.dynamic_lstm(input, size, h_0=None, c_0=None, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', dtype='float32', name=None) - -:api_attr: 声明式编程模式（静态图) - - - -该OP实现了 LSTM，即 Long-Short Term Memory（长短期记忆）运算 - `Hochreiter, S., & Schmidhuber, J. (1997) `_。 - -.. note:: - - 该OP仅支持 LoDTensor 作为输入，如果您需要处理的是Tensor，请使用 :ref:`cn_api_fluid_layers_lstm` 。 - - 在实现的时候为了提升效率，用户必须将LSTM的输入先进行线性映射，将维度为 [T, hidden_size] 的输入映射为 [T, 4 × hidden_size] 输入，然后再传给该OP。 - -该OP的默认实现方式为 diagonal/peephole 连接，参见 `Gers, F. A., & Schmidhuber, J. (2000) `_。 -如果需要禁用 peephole 连接方法，将 use_peepholes 设为 False 即可。 - -该OP对于序列中每一个时间步的计算公式如下： - -.. math:: - i_t=\sigma (W_{ix}x_{t}+W_{ih}h_{t-1}+W_{ic}c_{t-1}+b_i) -.. math:: - f_t=\sigma (W_{fx}x_{t}+W_{fh}h_{t-1}+W_{fc}c_{t-1}+b_f) -.. math:: - o_t=\sigma (W_{ox}x_{t}+W_{oh}h_{t-1}+W_{oc}c_{t-1}+b_o) -.. math:: - \widetilde{c_t}=act_g(W_{ct}x_{t}+W_{ch}h_{t-1}+b_{c}) -.. math:: - c_t=f_t\odot c_{t-1}+i_t\odot \widetilde{c_t} -.. math:: - h_t=o_t\odot act_h(c_t) - -公式中的概念信息如下： - - :math:`x_{t}` 表示时间步 :math:`t` 的输入 - - :math:`h_{t}` 表示时间步 :math:`t` 的 hidden 状态 - - :math:`h_{t-1}, c_{t-1}` 分别表示前一个时间步的 hidden 和 cell 状态 - - :math:`\widetilde{c_t}` 表示候选的 cell 状态 - - :math:`i_t` ，:math:`f_t` 和 :math:`o_t` 分别为 input gate，forget gate，output gate - - :math:`W` 表示 weight （例如， :math:`W_{ix}` 是在计算 input gate :math:`i_t` 时，对输入 :math:`x_{t}` 做线性变换的 weight） - - :math:`b` 表示 bias （例如， :math:`b_{i}` 是 input gate 的 bias） - - :math:`\sigma` 表示 gate 的非线性激活函数，默认为 sigmoid - - :math:`act_g， act_h` 分别表示 cell 输入和 cell 输出的非线性激活函数，默认为 tanh - - :math:`\odot` 表示矩阵的 Hadamard product，即对两个维度相同的矩阵，将相同位置的元素相乘，得到另一个维度相同的矩阵 - -参数: - - **input** ( :ref:`api_guide_Variable` ) 维度为 :math:`[T, 4*hidden\_size]` 的多维 LoDTensor（必须在传入该OP前对维度为 :math:`[T, hidden\_size]` 的输入经过线性变换得到），其中 T 为 batch 中所有样本的长度之和，hidden_size 为隐层大小，数据类型为 float32 或者 float64。 - - **size** (int) – 必须为 4*hidden_size。 - - **h_0** ( :ref:`api_guide_Variable` ，可选) 维度为 :math:`[batch\_size, hidden\_size]` 的多维 Tensor，其中 hidden_size 为隐层大小，数据类型为 float32 或者 float64。如果为 None，该OP会自动设置为全0的向量。默认值为None。 - - **c_0** ( :ref:`api_guide_Variable` ，可选) 维度为 :math:`[batch\_size, hidden\_size]` 的多维 Tensor，其中 hidden_size 为隐层大小，数据类型为 float32 或者 float64。如果为 None，该OP会自动设置为全0的向量；:math:`h_0, c_0` 如果要设置为None，必须同时为None。默认值为None。 - - **param_attr** (ParamAttr，可选) – 指定权重参数属性的对象。如果为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。如果用户需要设置此属性，维度必须等于 :math:`[hidden\_size, 4*hidden\_size]`。默认值为None。 - - **bias_attr** (ParamAttr，可选) – 指定偏置参数属性的对象。如果为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。如果用户需要设置此属性，如果 use_peepholes=true，维度需为 :math:`[1, 4*hidden\_size]`, use_peepholes=true，维度需为 :math:`[1, 7*hidden\_size]`。默认值为None。 - - **use_peepholes** (bool，可选) – 是否使用 peephole 连接。默认值为True。 - - **is_reverse** (bool，可选) – 是否将输入的数据根据根据样本长度进行逆序，同时会将输出进行逆序，用户拿到结果之后，不需要再逆序。默认值为False。 - - **gate_activation** (str，可选) – 应用于input gate，forget gate， output gate 的激活函数。默认值为sigmoid。 - - **cell_activation** (str，可选) – 用于cell输入的激活函数。默认值为tanh。 - - **candidate_activation** (str，可选) – 用于cell输出的激活函数。默认值为tanh。 - - **dtype** (str，可选) – 数据类型为 float32 或者 float64。默认值为 float32。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 - -返回：经过lstm运算输出的 hidden 和 cell 的状态的tuple，包括 - -- hidden：LSTM hidden的输出结果，维度为 :math:`[T, hidden\_size]` 的LoDTensor，且LoD保持与输入一致，数据类型与input一致。 -- cell：LSTM cell的输出结果，维度为 :math:`[T, hidden\_size]` 的LoDTensor，且LoD保持与输入一致，数据类型与input一致。 - -返回类型: tuple（ :ref:`api_guide_Variable` , :ref:`api_guide_Variable` ） - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - emb_dim = 256 - vocab_size = 10000 - hidden_dim = 512 - - data = fluid.layers.data(name='x', shape=[1], dtype='int32', lod_level=1) - emb = fluid.layers.embedding(input=data, size=[vocab_size, emb_dim], is_sparse=True) - - forward_proj = fluid.layers.fc(input=emb, size=hidden_dim * 4, bias_attr=False) - forward, cell = fluid.layers.dynamic_lstm(input=forward_proj, size=hidden_dim * 4, use_peepholes=False) - forward.shape # (-1, 512) - cell.shape # (-1, 512) - - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/embedding_cn.rst b/doc/paddle/api/paddle/fluid/layers/embedding_cn.rst index ee70bead5caa9abd9db685f1709cae196ced9028..b5ad3607114832a799d763d7d68b05a60d65a55d 100644 --- a/doc/paddle/api/paddle/fluid/layers/embedding_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/embedding_cn.rst @@ -1,18 +1,22 @@ -.. _cn_api_fluid_embedding: +.. _cn_api_fluid_layers_embedding: embedding ------------------------------- -.. py:function:: paddle.fluid.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') +.. py:function:: paddle.fluid.layers.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') :api_attr: 声明式编程模式（静态图) -该OP根据input中的id信息从embedding矩阵中查询对应embedding信息，函数会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。 +嵌入层(Embedding Layer) -输出的Tensor的shape是在输入Tensor shape的最后一维后面添加了emb_size的维度。 +**注意：此OP将在未来的版本中被移除！该OP要求输入Tensor shape的最后一维必须为1。推荐使用fluid.** :ref:`cn_api_fluid_embedding` 。 + +该OP根据input中的id信息从embedding矩阵中查询对应embedding信息，并会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。 + +要求input的最后一维必须等于1，输出的Tensor的shape是将输入Tensor shape的最后一维的1替换为emb_size。 注：input中的id必须满足 ``0 =< id < size[0]``，否则程序会抛异常退出。 @@ -22,8 +26,8 @@ embedding Case 1: input是Tensor, 且padding_idx = -1 - input.data = [[1, 3], [2, 4], [4, 127]] - input.shape = [3, 2] + input.data = [[[1], [3]], [[2], [4]], [[4], [127]]] + input.shape = [3, 2, 1] 若size = [128, 16] 输出为Tensor: out.shape = [3, 2, 16] @@ -32,7 +36,7 @@ embedding [[0.345249859, 0.124939536, ..., 0.194353745], [0.945345345, 0.435394634, ..., 0.435345365]], - + [[0.945345345, 0.435394634, ..., 0.435345365], [0.0, 0.0, ..., 0.0 ]]] # padding data 输入的padding_idx小于0，则自动转换为padding_idx = -1 + 128 = 127, 对于输入id为127的词，进行padding处理。 @@ -46,25 +50,25 @@ embedding 若size = [128, 16] 输出为LoDTensor: out.lod = [[2, 3]] - out.shape = [5, 1, 16] - out.data = [[[0.129435295, 0.244512452, ..., 0.436322452]], - [[0.345421456, 0.524563927, ..., 0.144534654]], - [[0.345249859, 0.124939536, ..., 0.194353745]], - [[0.945345345, 0.435394634, ..., 0.435345365]], - [[0.0, 0.0, ..., 0.0 ]]] # padding data + out.shape = [5, 16] + out.data = [[0.129435295, 0.244512452, ..., 0.436322452], + [0.345421456, 0.524563927, ..., 0.144534654], + [0.345249859, 0.124939536, ..., 0.194353745], + [0.945345345, 0.435394634, ..., 0.435345365], + [0.0, 0.0, ..., 0.0 ]] # padding data 输入的padding_idx = 0，则对于输入id为0的词，进行padding处理。 参数： - - **input** (Variable) - 存储id信息的Tensor或LoDTensor，数据类型必须为：int64。input中的id必须满足 ``0 =< id < size[0]`` 。 + - **input** (Variable) - 存储id信息的Tensor或LoDTensor，数据类型必须为：int64，输入的shape最后一维须为1。input中的id必须满足 ``0 =< id < size[0]`` 。 - **size** (tuple|list) - embedding矩阵的维度。必须包含两个元素，第一个元素为vocab_size(词表大小), 第二个为emb_size（embedding层维度）。 - **is_sparse** (bool) - 是否使用稀疏的更新方式，这个参数只会影响反向的梯度更新的性能，sparse更新速度更快，推荐使用稀疏更新的方式。但某些optimizer不支持sparse更新，比如 :ref:`cn_api_fluid_optimizer_AdadeltaOptimizer` 、 :ref:`cn_api_fluid_optimizer_AdamaxOptimizer` 、 :ref:`cn_api_fluid_optimizer_DecayedAdagradOptimizer` 、 :ref:`cn_api_fluid_optimizer_FtrlOptimizer` 、 :ref:`cn_api_fluid_optimizer_LambOptimizer` 、:ref:`cn_api_fluid_optimizer_LarsMomentumOptimizer` ，此时is_sparse必须为False。默认为False。 - **is_distributed** (bool) - 是否使用分布式的方式存储embedding矩阵，仅在多机分布式cpu训练中使用。默认为False。 - - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx 会被改成 vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为none，不作处理，默认为None。 + - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx会被改成vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为None，不作处理，默认为None。 - **param_attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为numpy数据格式，且保证本地词向量的shape和embedding的 ``size`` 参数一致，然后使用 :ref:`cn_api_fluid_initializer_NumpyArrayInitializer` 进行初始化，即可实现加载自定义或预训练的词向量。详细使用方法见代码示例2。 - - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32，float64，默认为float32。 + - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32或float64，默认为float32。 -返回：input映射后embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 +返回：input映射后得到的Embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 返回类型：Variable @@ -73,10 +77,12 @@ embedding .. code-block:: python import paddle.fluid as fluid + import numpy as np + data = fluid.layers.data(name='sequence', shape=[1], dtype='int64', lod_level=1) # 示例 1 - emb_1 = fluid.embedding(input=data, size=[128, 64]) + emb_1 = fluid.layers.embedding(input=data, size=[128, 64]) # 示例 2: 加载用户自定义或预训练的词向量 weight_data = np.random.random(size=(128, 100)) # numpy格式的词向量数据 @@ -85,7 +91,7 @@ embedding learning_rate=0.5, initializer=fluid.initializer.NumpyArrayInitializer(weight_data), trainable=True) - emb_2 = fluid.embedding(input=data, size=(128, 100), param_attr=w_param_attrs, dtype='float32') + emb_2 = fluid.layers.embedding(input=data, size=(128, 100), param_attr=w_param_attrs, dtype='float32') diff --git a/doc/paddle/api/paddle/fluid/layers/eye_cn.rst b/doc/paddle/api/paddle/fluid/layers/eye_cn.rst index b0fb8b5ecb68711e3d196c92beaa87f9bb6e10fc..6044ab6e322580b82e1aa1e830b3c23554506c98 100644 --- a/doc/paddle/api/paddle/fluid/layers/eye_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/eye_cn.rst @@ -18,10 +18,6 @@ eye 返回： ``shape`` 为batch_shape + [num_rows, num_columns]的Tensor。 -抛出异常： - - ``TypeError``: - 如果 ``dtype`` 的类型不是float16， float32， float64， int32， int64其中之一。 - - ``TypeError``: - 如果 ``num_columns`` 不是非负整数或者 ``num_rows`` 不是非负整数。 - **代码示例**： .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/layers/fc_cn.rst b/doc/paddle/api/paddle/fluid/layers/fc_cn.rst deleted file mode 100644 index 6613b2d8879ab55272add049cb8461999f52866c..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/fc_cn.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _cn_api_fluid_layers_fc: - -fc -------------------------------- - - -.. py:function:: paddle.fluid.layers.fc(input, size, num_flatten_dims=1, param_attr=None, bias_attr=None, act=None, name=None) - -:api_attr: 声明式编程模式（静态图) - - - - -**全连接层** - -该OP将在神经网络中构建一个全连接层。其输入可以是一个Tensor（或LoDTensor）或多个Tensor（或LoDTensor）组成的list（详见参数说明），该OP会为每个输入的Tensor创建一个权重（weights）变量，即一个从每个输入单元到每个输出单元的全连接权重矩阵。FC层将每个输入Tensor和其对应的权重(weights)相乘得到shape为 :math:`[M, size]` 输出Tensor，其中 ``M`` 为batch_size大小。如果有多个输入Tensor，则多个shape为 :math:`[M, size]` 的Tensor计算结果会被累加起来，作为最终输出。如果 ``bias_attr`` 非空，则会创建一个偏置变量（bias variable），并把它累加到输出结果中。如果 ``act`` 非空，将会在输出结果上应用相应的激活函数。 - -当输入为单个Tensor（或LoDTensor）： - -.. math:: - - \\Out = Act({XW + b})\\ - - - -当输入为多个Tensor（或LoDTensor）组成的list时： - -.. math:: - - \\Out=Act(\sum^{N-1}_{i=0}X_iW_i+b) \\ - - -上述等式中： - - :math:`N` ：输入的数目，如果输入是Tensor列表，N等于len(input) - - :math:`X_i` ：第i个输入的Tensor - - :math:`W_i` ：对应第i个输入张量的第i个权重矩阵 - - :math:`b` ：该层创建的bias参数 - - :math:`Act` ：activation function(激活函数) - - :math:`Out` ：输出Tensor - -:: - - Case 1： - 给定单个输入Tensor data_1, 且num_flatten_dims = 2: - data_1.data = [[[0.1, 0.2], - [0.3, 0.4]]] - data_1.shape = (1, 2, 2) # 1是batch_size - - out = fluid.layers.fc(input=data_1, size=1， num_flatten_dims=2) - - 则输出为： - out.data = [[0.83234344], [0.34936576]] - out.shape = (1, 2, 1) - - - Case 2: - 给定多个Tensor组成的list: - data_1.data = [[[0.1, 0.2], - [0.3, 0.4]]] - data_1.shape = (1, 2, 2) # 1 是 batch_size - - data_2 = [[[0.1, 0.2, 0.3]]] - data_2.shape = (1, 1, 3) - - out = fluid.layers.fc(input=[data_1, data_2], size=2) - - 则输出为： - out.data = [[0.18669507, 0.1893476]] - out.shape = (1, 2) - - -参数: - - **input** (Variable|list of Variable) – 维度为 :math:`[N_1, N_2, ..., N_k]` 的多维Tensor（或LoDTensor）或由多个Tensor（或LoDTensor）组成的list，输入Tensor的shape至少是2。数据类型为float32或float64。 - - **size** (int) – 全连接层输出单元的数目，即输出Tensor（或LoDTensor）特征维度。 - - **num_flatten_dims** (int) – 输入可以接受维度大于2的Tensor。在计算时，输入首先会被扁平化（flatten）为一个二维矩阵，之后再与权重(weights)相乘。参数 ``num_flatten_dims`` 决定了输入Tensor的flatten方式: 前 ``num_flatten_dims`` (包含边界，从1开始数) 个维度会被扁平化为二维矩阵的第一维 (即为矩阵的高), 剩下的 :math:`rank(X) - num\_flatten\_dims` 维被扁平化为二维矩阵的第二维 (即矩阵的宽)。 例如， 假设X是一个五维的Tensor，其shape为(2, 3, 4, 5, 6), 若 :math:`num\_flatten\_dims = 3` ，则扁平化的矩阵shape为： :math:`(2 x 3 x 4, 5 x 6) = (24, 30)` ，最终输出Tensor的shape为 :math:`(2, 3, 4, size)` 。默认为1。 - - **param_attr** (ParamAttr) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **bias_attr** (ParamAttr) – 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **act** (str) – 应用于输出上的激活函数，如tanh、softmax、sigmoid，relu等，支持列表请参考 :ref:`api_guide_activations` ，默认值为None。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - - -返回：经过全连接层计算后的Tensor或LoDTensor，数据类型与input类型一致。 - -返回类型: Variable - -弹出异常：``ValueError`` - 如果输入Tensor（或LoDTensor）的维度小于2 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - # 当输入为单个张量时 - - data = fluid.layers.data(name="data", shape=[32, 32], dtype="float32") - fc = fluid.layers.fc(input=data, size=1000, act="tanh") - - # 当输入为多个张量时 - data_1 = fluid.layers.data(name="data_1", shape=[32, 32], dtype="float32") - data_2 = fluid.layers.data(name="data_2", shape=[24, 36], dtype="float32") - fc = fluid.layers.fc(input=[data_1, data_2], size=1000, act="tanh") - - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/fill_constant_cn.rst b/doc/paddle/api/paddle/fluid/layers/fill_constant_cn.rst index 83e1faebe223736a11d1ae0579cd152957468367..f7af206495c0640ef87b2806666fdf919015463e 100644 --- a/doc/paddle/api/paddle/fluid/layers/fill_constant_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/fill_constant_cn.rst @@ -27,6 +27,10 @@ fill_constant 返回类型：变量（Variable） +抛出异常： + - :code:`TypeError`: dtype必须是bool，float16，float32，float64，int32和int64之一，输出Tensor的数据类型必须与dtype相同。 + - :code:`TypeError`: 当 `shape` 的数据类型不是list、tuple、Variable。 + **代码示例**： .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/layers/flatten_cn.rst b/doc/paddle/api/paddle/fluid/layers/flatten_cn.rst deleted file mode 100644 index 3e314f655a8cf5b597daeac8507732a9c571d130..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/flatten_cn.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _cn_api_fluid_layers_flatten: - -flatten -------------------------------- - -.. py:function:: paddle.fluid.layers.flatten(x, axis=1, name=None) - -:alias_main: paddle.flatten -:alias: paddle.flatten,paddle.tensor.flatten,paddle.tensor.manipulation.flatten -:old_api: paddle.fluid.layers.flatten - - - -flatten op将输入的多维Tensor展平成2-D Tensor矩阵 - -例如： - -.. code-block:: text - - Case 1: - - 给定 - X.shape = (3, 100, 100, 4) - 且 - axis = 2 - 得到: - Out.shape = (3 * 100, 4 * 100) - - Case 2: - - 给定 - X.shape = (3, 100, 100, 4) - 且 - axis = 0 - 得到: - Out.shape = (1, 3 * 100 * 100 * 4) - -参数： - - **x** (Variable) - 一个维度数>=axis 的多维Tensor, 数据类型可以为float32，float64，int8，int32或int64。 - - **axis** (int) - flatten展开的分割轴，[0, axis) 轴数据被flatten到输出矩阵的0轴，[axis, R)数据被flatten到输出矩阵的1轴，其中R是输入张量的总维度数。axis的值必须在[0,R]范围内。当 axis=0 时，若输入Tensor的维度为 :math:`[d_0, d_1，… d_n]` ，则输出张量的Tensor维度为 :math:`[1，d_0 * d_1 *… d_n]` ，默认值为1。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回: 一个 2-D Tensor，它包含输入Tensor的数据，但维度发生变化。输入的[0, axis)维将沿axis展平到输出Tensor的0维度，剩余的输入维数展平到输出的1维度。数据类型与输入x相同。 - -返回类型: Variable - -抛出异常： - - ValueError: 如果 x 不是一个Variable - - ValueError: 如果axis的范围不在 [0, rank(x)] 范围内 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - x = fluid.layers.data(name="x", shape=[4, 4, 3], append_batch_size=False, dtype="float32") - # x shape is [4, 4, 3] - out = fluid.layers.flatten(x=x, axis=2) - # out shape is [16, 3] - - - diff --git a/doc/paddle/api/paddle/fluid/layers/gather_cn.rst b/doc/paddle/api/paddle/fluid/layers/gather_cn.rst index 7e1f85a6c8ed9f727c6a3d60a457c434f4321cbd..9d0caee7b263b87387fcffe9fc24861b8e3950f3 100644 --- a/doc/paddle/api/paddle/fluid/layers/gather_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/gather_cn.rst @@ -8,7 +8,7 @@ gather -根据索引 ``index`` 获取输入（input）的最外层维度的条目，并将它们拼接在一起。 +根据索引 ``index`` 获取输入 ``input`` 的最外层维度的条目，并将它们拼接在一起。 .. math:: @@ -29,13 +29,12 @@ gather 参数: - - **input** (Variable) - 输入, 秩 ``rank >= 1`` , 支持的数据类型包括 int32、int64、float32、float64 和 uint8 (CPU)、float16（GPU） 。 - - **index** (Variable) - 索引，秩 ``rank = 1``, 数据类型为 int32 或 int64。 + - **input** (Tensor) - 输入, 秩 ``rank >= 1`` , 支持的数据类型包括 int32、int64、float32、float64 和 uint8 (CPU)、float16（GPU） 。 + - **index** (Tensor) - 索引，秩 ``rank = 1``, 数据类型为 int32 或 int64。 - **overwrite** (bool) - 具有相同索引时在反向更新梯度的模式。如果为 ``True`` ，则使用覆盖模式更新相同索引的梯度；如果为 ``False`` ，则使用累积模式更新相同索引的梯度。默认值为 ``True`` 。 返回：和输入的秩相同的输出张量。 -返回类型：Variable **代码示例** diff --git a/doc/paddle/api/paddle/fluid/layers/gather_nd_cn.rst b/doc/paddle/api/paddle/fluid/layers/gather_nd_cn.rst index 6c810ad73aa1edff045883f98cd80ffcb2365762..8a570ff2e2840215d6d84712e244c192a2344d22 100644 --- a/doc/paddle/api/paddle/fluid/layers/gather_nd_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/gather_nd_cn.rst @@ -5,11 +5,6 @@ gather_nd .. py:function:: paddle.fluid.layers.gather_nd(input, index, name=None) -:alias_main: paddle.gather_nd -:alias: paddle.gather_nd,paddle.tensor.gather_nd,paddle.tensor.manipulation.gather_nd -:old_api: paddle.fluid.layers.gather_nd - - 该OP是 :code:`gather` 的高维推广，并且支持多轴同时索引。 :code:`index` 是一个K维度的张量，它可以认为是从 :code:`input` 中取K-1维张量，每一个元素是一个切片： @@ -56,18 +51,18 @@ gather_nd 参数： - - **input** (Variable) - 输入张量，数据类型可以是int32，int64，float32，float64, bool。 - - **index** (Variable) - 输入的索引张量，数据类型为非负int32或非负int64。它的维度 :code:`index.rank` 必须大于1，并且 :code:`index.shape[-1] <= input.rank` 。 - - **name** (string) - 该层的名字，默认值为None，表示会自动命名。 + - **input** (Tensor) - 输入Tensor，数据类型可以是int32，int64，float32，float64, bool。 + - **index** (Tensor) - 输入的索引Tensor，其数据类型为int32或者int64。它的维度 :code:`index.rank` 必须大于1，并且 :code:`index.shape[-1] <= input.rank` 。 + - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回：shape为index.shape[:-1] + input.shape[index.shape[-1]:]的Tensor|LoDTensor，数据类型与 :code:`input` 一致。 -返回类型：Variable **代码示例**： .. code-block:: python + import paddle import paddle.fluid as fluid x = fluid.layers.data(name='x', shape=[3, 4, 5], dtype='float32') index = fluid.layers.data(name='index', shape=[2, 2], dtype='int32') diff --git a/doc/paddle/api/paddle/fluid/layers/get_tensor_from_selected_rows_cn.rst b/doc/paddle/api/paddle/fluid/layers/get_tensor_from_selected_rows_cn.rst deleted file mode 100644 index 3a9b9268aa345959d50b69667659b77203777a7c..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/get_tensor_from_selected_rows_cn.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _cn_api_fluid_layers_get_tensor_from_selected_rows: - -get_tensor_from_selected_rows -------------------------------- - -.. py:function:: paddle.fluid.layers.get_tensor_from_selected_rows(x, name=None) - - - - -该OP从SelectedRows类型的输入中获取向量数据，以LoDTensor的形式输出。 - - -:: - - 例如： - - 输入为SelectedRows类型: - x.rows = [0, 5, 5, 4, 19] - x.height = 20 - x.value = [[1, 1] [2, 2] [2, 2] [3, 3] [6, 6]] - - 输出为LoDTensor： - out.shape = [5, 2] - out.data = [[1, 1], - [2, 2], - [2, 2], - [3, 3], - [6, 6]] - - -参数： - - **x** (SelectedRows) - SelectedRows类型的输入，数据类型为float32，float64，int32或int64。 - - **name** (str) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 - -返回： 从SelectedRows中转化而来的LoDTensor，数据类型和输入一致。 - -返回类型： Variable - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - b = fluid.default_main_program().global_block() - input = b.create_var(name="X", dtype="float32", persistable=True, type=fluid.core.VarDesc.VarType.SELECTED_ROWS) - out = fluid.layers.get_tensor_from_selected_rows(input) - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/grid_sampler_cn.rst b/doc/paddle/api/paddle/fluid/layers/grid_sampler_cn.rst deleted file mode 100644 index 8871106520eea576edbddf0b606e8113cfd4e85f..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/grid_sampler_cn.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. _cn_api_fluid_layers_grid_sampler: - -grid_sampler -------------------------------- - -.. py:function:: paddle.fluid.layers.grid_sampler(x, grid, name=None) - -:alias_main: paddle.nn.functional.grid_sampler -:alias: paddle.nn.functional.grid_sampler,paddle.nn.functional.vision.grid_sampler -:old_api: paddle.fluid.layers.grid_sampler - - - -该OP基于flow field网格的对输入X进行双线性插值采样。网格通常由affine_grid生成, shape为[N, H, W, 2]，是shape为[N, H, W]的采样点张量的(x, y)坐标。 -其中，x坐标是对输入数据X的第四个维度(宽度维度)的索引，y坐标是第三维度(高维度)的索引，最终输出采样值为采样点的4个最接近的角点的双线性插值结果，输出张量的shape为[N, C, H, W]。 - -step 1： - - 得到(x, y)网格坐标，缩放到[0,h -1/W-1] - -.. code-block:: text - - grid_x = 0.5 * (grid[:, :, :, 0] + 1) * (W - 1) grid_y = 0.5 * (grid[:, :, :, 1] + 1) * (H - 1) - -step 2： - - 在每个[H, W]区域用网格(X, y)作为输入数据X的索引，并将双线性插值点值由4个最近的点表示。 - -.. code-block:: text - - wn ------- y_n ------- en - | | | - | d_n | - | | | - x_w --d_w-- grid--d_e-- x_e - | | | - | d_s | - | | | - ws ------- y_s ------- wn - - x_w = floor(x) // west side x coord - x_e = x_w + 1 // east side x coord - y_n = floor(y) // north side y coord - y_s = y_s + 1 // south side y coord - d_w = grid_x - x_w // distance to west side - d_e = x_e - grid_x // distance to east side - d_n = grid_y - y_n // distance to north side - d_s = y_s - grid_y // distance to south side - wn = X[:, :, y_n, x_w] // north-west point value - en = X[:, :, y_n, x_e] // north-east point value - ws = X[:, :, y_s, x_w] // south-east point value - es = X[:, :, y_s, x_w] // north-east point value - - - output = wn * d_e * d_s + en * d_w * d_s - + ws * d_e * d_n + es * d_w * d_n - -参数： - - **x** (Variable): 输入张量，维度为 :math:`[N, C, H, W]` 的4-D Tensor，N为批尺寸，C是通道数，H是特征高度，W是特征宽度, 数据类型为float32或float64。 - - **grid** (Variable): 输入网格数据张量，维度为 :math:`[N, H, W, 2]` 的4-D Tensor，N为批尺寸，C是通道数，H是特征高度，W是特征宽度, 数据类型为float32或float64。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值：None。 - -返回： Variable(Tensor): 输入X基于输入网格的双线性插值计算结果，维度为 :math:`[N, C, H, W]` 的4-D Tensor - -返回类型：变量(Variable)，数据类型与 ``x`` 一致 - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - - # 一般与 affine_grid 组合使用 - x = fluid.data(name='x', shape=[None, 10, 32, 32], dtype='float32') - theta = fluid.layers.data(name='theta', shape=[2, 3], dtype='float32') - grid = fluid.layers.affine_grid(theta=theta, out_shape=[3, 10, 32, 32]) - out = fluid.layers.grid_sampler(x=x, grid=grid) - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/group_norm_cn.rst b/doc/paddle/api/paddle/fluid/layers/group_norm_cn.rst deleted file mode 100755 index 049a9e2f0055ca6ce3220c526f25f0abdd335c3d..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/group_norm_cn.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _cn_api_fluid_layers_group_norm: - -group_norm -------------------------------- - - -.. py:function:: paddle.fluid.layers.group_norm(input, groups, epsilon=1e-05, param_attr=None, bias_attr=None, act=None, data_layout='NCHW', name=None) - -:api_attr: 声明式编程模式（静态图) - - - -参考论文： `Group Normalization `_ - -参数： - - **input** (Variable)：输入为4-D Tensor，数据类型为float32或float64。 - - **groups** (int)：从 channel 中分离出来的 group 的数目，数据类型为int32。 - - **epsilon** (float，可选)：为防止方差除以零，增加一个很小的值。数据类型为float32。默认值：1e-05。 - - **param_attr** (ParamAttr|bool，可选) ：指定权重参数属性的对象。若 ``param_attr`` 为bool类型，只支持为False，表示没有权重参数。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **bias_attr** (ParamAttr|bool，可选) : 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **act** (str，可选)：将激活应用于输出的 group normalizaiton。 - - **data_layout** (str，可选)：指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 - - **name** (str，可选)：具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回：4-D Tensor，数据类型和格式与 `input` 一致。 - -返回类型：Variable - -抛出异常： - - ``ValueError`` - 如果 ``data_layout`` 既不是"NCHW"也不是"NHWC"。 - - ``ValueError`` - 如果 ``groups`` 小于1，或者 ``groups`` 大于输入的通道数。 - - ``ShapeError`` - 如果 ``param_attr`` (Scale) 或者 ``bias_attr`` (Bias) 不是 1-D Tensor。 - - ``ShapeError`` - 如果 ``param_attr`` (Scale) 或者 ``bias_attr`` (Bias) 的大小与输入的通道数不相等。 - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.data(name='data', shape=[None, 8, 32, 32], dtype='float32') - x = fluid.layers.group_norm(input=data, groups=4) - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/hash_cn.rst b/doc/paddle/api/paddle/fluid/layers/hash_cn.rst deleted file mode 100644 index a25828a10dc67b9697541d6e83234272ffbbb81a..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/hash_cn.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _cn_api_fluid_layers_hash: - -hash -------------------------------- - -.. py:function:: paddle.fluid.layers.hash(input, hash_size, num_hash=1, name=None) - -:alias_main: paddle.nn.functional.hash -:alias: paddle.nn.functional.hash,paddle.nn.functional.lod.hash -:old_api: paddle.fluid.layers.hash - - - -该OP将输入 hash 成为一个整数，该数的值小于给定的 ``hash_size`` 。**仅支持输入为LoDTensor**。 - -该OP使用的哈希算法是：xxHash - `Extremely fast hash algorithm `_ - - -参数： - - **input** (Variable) - 输入是一个 **二维** ``LoDTensor`` 。**输入维数必须为2**。数据类型为：int32、int64。**仅支持LoDTensor**。 - - **hash_size** (int) - 哈希算法的空间大小。输出值将保持在 :math:`[0, hash\_size)` 范围内。 - - **num_hash** (int) - 哈希次数。默认值为1。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回：``LoDTensor`` - -返回类型：Variable - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - place = fluid.core.CPUPlace() - - # 构建网络 - x = fluid.data(name="x", shape=[2, 2], dtype="int32", lod_level=1) - res = fluid.layers.hash(name="res", input=x, hash_size=1000, num_hash=4) - - # 创建CPU执行器 - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - - in1 = np.array([[1,2],[3,4]]).astype("int32") - print(in1) - x_i = fluid.create_lod_tensor(in1, [[0, 2]], place) - res = exe.run(fluid.default_main_program(), feed={'x':x_i}, fetch_list=[res], return_numpy=False) - print(np.array(res[0])) - # [[[722] - # [407] - # [337] - # [395]] - # [[603] - # [590] - # [386] - # [901]]] diff --git a/doc/paddle/api/paddle/fluid/layers/linspace_cn.rst b/doc/paddle/api/paddle/fluid/layers/linspace_cn.rst index ca9775016b06c55b7504d31d913aeaad1df76466..c301233b746178e17db08dacbf927d0b0b5a89f7 100644 --- a/doc/paddle/api/paddle/fluid/layers/linspace_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/linspace_cn.rst @@ -5,25 +5,18 @@ linspace .. py:function:: paddle.fluid.layers.linspace(start, stop, num, dtype=None, name=None) - - - 该OP返回一个Tensor，Tensor的值为在区间start和stop上均匀间隔的num个值，输出Tensor的长度为num。 **注意：该OP不进行梯度计算** 参数： - - **start** (float|Tensor) – ``start`` 是区间开始的变量，可以是一个浮点标量，或是一个shape为[1]的Tensor，该Tensor的数据类型可以是float32或者是float64。 - - **stop** (float|Tensor) – ``end`` 是区间结束的变量，可以是一个浮点标量，或是一个shape为[1]的Tensor，该Tensor的数据类型可以是float32或者是float64。 + - **start** (int|float|Tensor) – ``start`` 是区间开始的变量，可以是一个浮点标量，或是一个shape为[1]的Tensor，该Tensor的数据类型可以是float32，float64，int32 或者int64。 + - **stop** (int|float|Tensor) – ``stop`` 是区间结束的变量，可以是一个浮点标量，或是一个shape为[1]的Tensor，该Tensor的数据类型可以是float32，float64，int32或者int64。 - **num** (int|Tensor) – ``num`` 是给定区间内需要划分的区间数，可以是一个整型标量，或是一个shape为[1]的Tensor，该Tensor的数据类型需为int32。 - - **dtype** (string, 可选) – 输出Tensor的数据类型，可以是float32或者是float64，如果dtype的数据类型为None，输出Tensor数据类型为float32。 + - **dtype** (np.dtype|str, 可选) – 输出Tensor的数据类型，可以是float32，float64， int32或者int64。如果dtype的数据类型为None，输出Tensor数据类型为float32。 - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回：表示等间隔划分结果的1-D Tensor，该Tensor的shape大小为 :math:`[num]` ，在mum为1的情况下，仅返回包含start元素值的Tensor。 -抛出异常： - - ``TypeError`` - 当start或者stop的数据类型不是float32或者float64。 - - ``TypeError`` - 当num的数据类型不是float32或者float64。 - - ``TypeError`` - 当dtype的类型不是float32或者float64。 **代码示例**： diff --git a/doc/paddle/api/paddle/fluid/layers/load_cn.rst b/doc/paddle/api/paddle/fluid/layers/load_cn.rst index a12a65fbed8eacfcf1f17246fc3ee3001dd81c70..f001976971c5e84eb93c62fa5a5d77c8f2a9a335 100644 --- a/doc/paddle/api/paddle/fluid/layers/load_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/load_cn.rst @@ -1,55 +1,168 @@ -.. _cn_api_fluid_load: +.. _cn_api_fluid_dygraph_jit_load: load -------------------------------- - -.. py:function:: paddle.fluid.load(program, model_path, executor=None, var_list=None) - -:api_attr: 声明式编程模式（静态图) - - - -该接口从Program中过滤出参数和优化器信息，然后从文件中获取相应的值。 - -如果Program和加载的文件之间参数的维度或数据类型不匹配，将引发异常。 - -该函数还可以加载用[save_params，save_persistables，save_vars]接口保存的模型文件。 -当[save_params，save_persistables，save_vars]保存的模型格式为单个大文件时，var_list不能为None。 - -参数: - - **program** ( :ref:`cn_api_fluid_Program` ) – 要加载的Program。 - - **model_path** (str) – 保存Program的目录名称+文件前缀。格式为 ``目录名称/文件前缀`` 。 - - **executor** (Executor, 可选) - 当startup program没有运行时，用于初始化参数的Executor。默认值：None。 - - **var_list** (list, 可选) - 指定加载的变量列表，该参数只在加载旧接口[save_params，save_persistables，save_vars]保存的模型文件时使用。当加载的是多个小文件时，变量列表可以是所有加载文件中变量的子集；当加载的单个大文件时，变量列表必须和加载文件中的变量保持一致。 - -返回: 无 - -**代码示例** - -.. code-block:: python - - # example1 - import paddle.fluid as fluid - - x = fluid.data( name="x", shape=[10, 10], dtype='float32') - y = fluid.layers.fc(x, 10) - z = fluid.layers.fc(y, 10) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - fluid.save(fluid.default_main_program(), "./test_path") - fluid.load(fluid.default_main_program(), "./test_path") - - # example2 - # 注意example1和example2应该分开执行，避免干扰。 - import paddle.fluid as fluid - - x = fluid.data( name="x", shape=[10, 10], dtype='float32') - y = fluid.layers.fc(x, 10) - z = fluid.layers.fc(y, 10) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - fluid.save(fluid.default_main_program(), "./test_path") - fluid.load(fluid.default_main_program(), "./test_path", exe) - +----------------- + +.. py:function:: paddle.fluid.dygraph.jit.load(model_path, configs=None) + +:api_attr: 命令式编程模式（动态图) + +将接口 :ref:`cn_api_fluid_dygraph_jit_save` 或者 :ref:`cn_api_fluid_io_save_inference_model` 存储的模型载入为 :ref:`cn_api_fluid_dygraph_TranslatedLayer` ，用于预测推理或者fine-tune训练。 + +.. note:: + 由于一些历史原因，如果载入的模型是通过 :ref:`cn_api_fluid_io_save_inference_model` 存储的， + 在使用它进行fine-tune训练时会存在一些局限： + 1. 命令式编程模式不支持 ``LoDTensor`` ，所有原先输入变量或者参数依赖于LoD信息的模型暂时无法使用； + 2. 所有存储模型的feed变量都需要被传入 ``Translatedlayer`` 的forward方法； + 3. 原模型变量的 ``stop_gradient`` 信息已丢失且无法准确恢复； + 4. 原模型参数的 ``trainable`` 信息已丢失且无法准确恢复。 + +参数： + - **model_path** (str) - 存储模型的目录。 + - **configs** (SaveLoadConfig, 可选) - 用于指定额外配置选项的 :ref:`cn_api_fluid_dygraph_jit_SaveLoadConfig` 对象。默认为 ``None``。 + +返回：TranslatedLayer - 一个能够执行存储模型的 ``Layer`` 对象。 + +**示例代码** + +1. 载入由接口 :ref:`cn_api_fluid_dygraph_jit_save` 存储的模型进行预测推理及fine-tune训练。 + + .. code-block:: python + + import numpy as np + import paddle.fluid as fluid + from paddle.fluid.dygraph import Linear + from paddle.fluid.dygraph import declarative + BATCH_SIZE = 32 + BATCH_NUM = 20 + def random_batch_reader(): + def _get_random_images_and_labels(image_shape, label_shape): + image = np.random.random(size=image_shape).astype('float32') + label = np.random.random(size=label_shape).astype('int64') + return image, label + def __reader__(): + for _ in range(BATCH_NUM): + batch_image, batch_label = _get_random_images_and_labels( + [BATCH_SIZE, 784], [BATCH_SIZE, 1]) + yield batch_image, batch_label + return __reader__ + class LinearNet(fluid.dygraph.Layer): + def __init__(self, in_size, out_size): + super(LinearNet, self).__init__() + self._linear = Linear(in_size, out_size) + @declarative + def forward(self, x): + return self._linear(x) + # 开启命令式编程模式 + fluid.enable_dygraph() + # 1. 训练存储模型. + # 创建网络 + net = LinearNet(784, 1) + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=net.parameters()) + # 创建DataLoader + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + # 训练 + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = net(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + net.clear_gradients() + model_path = "linear.example.model" + fluid.dygraph.jit.save( + layer=net, + model_path=model_path, + input_spec=[img]) + # 2. 载入模型 & 预测 + # 载入模型 + infer_net = fluid.dygraph.jit.load(model_path) + # 预测 + x = fluid.dygraph.to_variable(np.random.random((1, 784)).astype('float32')) + pred = infer_net(x) + # 3. 载入模型 & fine-tune训练 + # 载入模型 + train_net = fluid.dygraph.jit.load(model_path) + train_net.train() + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=train_net.parameters()) + # 创建DataLoader + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + # fine-tune训练 + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = train_net(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + train_net.clear_gradients() + + +2. 载入由接口 :ref:`cn_api_fluid_io_save_inference_model` 存储的模型进行预测推理及fine-tune训练。 + + .. code-block:: python + + import numpy as np + import paddle.fluid as fluid + BATCH_SIZE = 32 + BATCH_NUM = 20 + def random_batch_reader(): + def _get_random_images_and_labels(image_shape, label_shape): + image = np.random.random(size=image_shape).astype('float32') + label = np.random.random(size=label_shape).astype('int64') + return image, label + def __reader__(): + for _ in range(BATCH_NUM): + batch_image, batch_label = _get_random_images_and_labels( + [BATCH_SIZE, 784], [BATCH_SIZE, 1]) + yield batch_image, batch_label + return __reader__ + img = fluid.data(name='img', shape=[None, 784], dtype='float32') + label = fluid.data(name='label', shape=[None, 1], dtype='int64') + pred = fluid.layers.fc(input=img, size=10, act='softmax') + loss = fluid.layers.cross_entropy(input=pred, label=label) + avg_loss = fluid.layers.mean(loss) + optimizer = fluid.optimizer.SGD(learning_rate=0.001) + optimizer.minimize(avg_loss) + place = fluid.CPUPlace() + exe = fluid.Executor(place) + exe.run(fluid.default_startup_program()) + loader = fluid.io.DataLoader.from_generator( + feed_list=[img, label], capacity=5, iterable=True) + loader.set_batch_generator(random_batch_reader(), places=place) + # 1. 训练 & 存储预测模型 + for data in loader(): + exe.run( + fluid.default_main_program(), + feed=data, + fetch_list=[avg_loss]) + model_path = "fc.example.model" + fluid.io.save_inference_model( + model_path, ["img"], [pred], exe) + # 开启命令式编程模式 + fluid.enable_dygraph() + # 2. 载入模型 & 预测 + fc = fluid.dygraph.jit.load(model_path) + x = fluid.dygraph.to_variable(np.random.random((1, 784)).astype('float32')) + pred = fc(x) + # 3. 载入模型 & fine-tune训练 + fc = fluid.dygraph.jit.load(model_path) + fc.train() + sgd = fluid.optimizer.SGD(learning_rate=0.001, + parameter_list=fc.parameters()) + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator( + random_batch_reader(), places=place) + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = fc(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + sgd.minimize(avg_loss) diff --git a/doc/paddle/api/paddle/fluid/layers/logical_and_cn.rst b/doc/paddle/api/paddle/fluid/layers/logical_and_cn.rst deleted file mode 100644 index 09e3efbcbcac121b94fc557a2ccee27357bfac80..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/logical_and_cn.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _cn_api_fluid_layers_logical_and: - -logical_and -------------------------------- - -.. py:function:: paddle.logical_and(x, y, out=None, name=None) - -该OP逐元素的对 ``x`` 和 ``y`` 进行逻辑与运算。 - -.. math:: - Out = X \&\& Y - -.. note:: - ``paddle.logical_and`` 遵守broadcasting，如您想了解更多，请参见 :ref:`cn_user_guide_broadcasting` 。 - -参数： - - **x** （Tensor）- 输入的 `Tensor` ，数据类型为：bool。 - - **y** （Tensor）- 输入的 `Tensor` ，数据类型为：bool。 - - **out** （Tensor，可选）- 指定算子输出结果的 `Tensor` ，可以是程序中已经创建的任何Tensor。默认值为None，此时将创建新的Tensor来保存输出结果。 - - **name** （str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 - -返回： ``Tensor`` ， 维度``x`` 维度相同，存储运算后的结果。 - -**代码示例：** - -.. code-block:: python - - import paddle - import numpy as np - - paddle.disable_static() - x_data = np.array([True], dtype=np.bool) - y_data = np.array([True, False, True, False], dtype=np.bool) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - res = paddle.logical_and(x, y) - print(res.numpy()) # [True False True False] diff --git a/doc/paddle/api/paddle/fluid/layers/logical_not_cn.rst b/doc/paddle/api/paddle/fluid/layers/logical_not_cn.rst deleted file mode 100644 index 3eaf0f1719abac0ce3e63ed2867026f349e76fba..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/logical_not_cn.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _cn_api_fluid_layers_logical_not: - -logical_not -------------------------------- - -.. py:function:: paddle.logical_not(x, out=None, name=None) - -:alias_main: paddle.logical_not -:alias: paddle.logical_not, paddle.tensor.logical_not, paddle.tensor.logic.logical_not -:old_api: paddle.fluid.layers.logical_not - - - -该OP逐元素的对 ``X`` Variable进行逻辑非运算 - -.. math:: - Out = !X - -参数： - - **x** （Variable）- 逻辑非运算的输入，是一个 Variable，数据类型只能是bool。 - - **out** （Variable，可选）- 指定算子输出结果的 Variable，可以是程序中已经创建的任何 Variable。默认值为None，此时将创建新的Variable来保存输出结果。 - - **name** （str，可选）- 该参数供开发人员打印调试信息时使用，具体用法参见 :ref:`api_guide_Name` ，默认值为None。 - -返回：与 ``x`` 维度相同，数据类型相同的 Variable。 - -返回类型：Variable - -**代码示例：** - -.. code-block:: python - - import paddle - import numpy as np - - paddle.enable_imperative() - x_data = np.array([True, False, True, False], dtype=np.bool) - x = paddle.imperative.to_variable(x_data) - res = paddle.logical_not(x) - print(res.numpy()) # [False True False True] diff --git a/doc/paddle/api/paddle/fluid/layers/logical_or_cn.rst b/doc/paddle/api/paddle/fluid/layers/logical_or_cn.rst deleted file mode 100644 index 9cb3420ea323948e47209be35dada5a85d2d51ea..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/logical_or_cn.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _cn_api_fluid_layers_logical_or: - -logical_or -------------------------------- - -.. py:function:: paddle.logical_or(x, y, out=None, name=None) - -该OP逐元素的对 ``X`` 和 ``Y`` 进行逻辑或运算。 - -.. math:: - Out = X || Y - -.. note:: - ``paddle.logical_or`` 遵守broadcasting，如您想了解更多，请参见 :ref:`cn_user_guide_broadcasting` 。 - -参数： - - **x** （Tensor）- 输入的 `Tensor` ，数据类型为：bool。 - - **y** （Tensor）- 输入的 `Tensor` ，数据类型为：bool。 - - **out** （Tensor，可选）- 指定算子输出结果的 `Tensor` ，可以是程序中已经创建的任何Tensor。默认值为None，此时将创建新的Tensor来保存输出结果。 - - **name** （str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 - -返回： ``Tensor`` ， 维度``x`` 维度相同，存储运算后的结果。 - -**代码示例：** - -.. code-block:: python - - import paddle - import numpy as np - - paddle.disable_static() - x_data = np.array([True, False], dtype=np.bool).reshape(2, 1) - y_data = np.array([True, False, True, False], dtype=np.bool).reshape(2, 2) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - res = paddle.logical_or(x, y) - print(res.numpy()) # [[ True True] [ True False]] diff --git a/doc/paddle/api/paddle/fluid/layers/logical_xor_cn.rst b/doc/paddle/api/paddle/fluid/layers/logical_xor_cn.rst deleted file mode 100644 index 502a5a60e55ea3384cc5a2b579118085bccb9e1f..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/logical_xor_cn.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _cn_api_fluid_layers_logical_xor: - -logical_xor -------------------------------- - -.. py:function:: paddle.logical_xor(x, y, out=None, name=None) - -该OP逐元素的对 ``X`` 和 ``Y`` 进行逻辑异或运算。 - -.. math:: - Out = (X || Y) \&\& !(X \&\& Y) - -.. note:: - ``paddle.logical_xor`` 遵守broadcasting，如您想了解更多，请参见 :ref:`cn_user_guide_broadcasting` 。 - -参数： - - **x** （Tensor）- 输入的 `Tensor` ，数据类型为：bool。 - - **y** （Tensor）- 输入的 `Tensor` ，数据类型为：bool。 - - **out** （Tensor，可选）- 指定算子输出结果的 `Tensor` ，可以是程序中已经创建的任何Tensor。默认值为None，此时将创建新的Tensor来保存输出结果。 - - **name** （str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 - -返回： ``Tensor`` ， 维度``x`` 维度相同，存储运算后的结果。 - -**代码示例：** - -.. code-block:: python - - import paddle - import numpy as np - - paddle.disable_static() - x_data = np.array([True, False], dtype=np.bool).reshape([2, 1]) - y_data = np.array([True, False, True, False], dtype=np.bool).reshape([2, 2]) - x = paddle.to_tensor(x_data) - y = paddle.to_tensor(y_data) - res = paddle.logical_xor(x, y) - print(res.numpy()) # [[False, True], [ True, False]] diff --git a/doc/paddle/api/paddle/fluid/layers/lstm_cn.rst b/doc/paddle/api/paddle/fluid/layers/lstm_cn.rst deleted file mode 100644 index f42882efaf70c2827f07bc1bbd4f14f0e4710589..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/lstm_cn.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. _cn_api_fluid_layers_lstm: - -lstm -------------------------------- - - -.. py:function:: paddle.fluid.layers.lstm(input, init_h, init_c, max_len, hidden_size, num_layers, dropout_prob=0.0, is_bidirec=False, is_test=False, name=None, default_initializer=None, seed=-1) - -:api_attr: 声明式编程模式（静态图) - - - -.. note:: - 该OP仅支持 GPU 设备运行 - -该OP实现了 LSTM，即 Long-Short Term Memory（长短期记忆）运算 - `Hochreiter, S., & Schmidhuber, J. (1997) `_。 - -该OP的实现不包括 diagonal/peephole 连接，参见 `Gers, F. A., & Schmidhuber, J. (2000) `_。 -如果需要使用 peephole 连接方法，请使用 :ref:`cn_api_fluid_layers_dynamic_lstm` 。 - -该OP对于序列中每一个时间步的计算公式如下： - -.. math:: - i_t = \sigma(W_{ix}x_{t} + W_{ih}h_{t-1} + b_{x_i} + b_{h_i}) -.. math:: - f_t = \sigma(W_{fx}x_{t} + W_{fh}h_{t-1} + b_{x_f} + b_{h_f}) -.. math:: - o_t = \sigma(W_{ox}x_{t} + W_{oh}h_{t-1} + b_{x_o} + b_{h_o}) -.. math:: - \widetilde{c_t} = tanh(W_{cx}x_t + W_{ch}h_{t-1} + b{x_c} + b_{h_c}) -.. math:: - c_t = f_t \odot c_{t-1} + i_t \odot \widetilde{c_t} -.. math:: - h_t = o_t \odot tanh(c_t) - -公式中的概念信息如下： - - :math:`x_{t}` 表示时间步 :math:`t` 的输入 - - :math:`h_{t}` 表示时间步 :math:`t` 的 hidden 状态 - - :math:`h_{t-1}, c_{t-1}` 分别表示前一个时间步的 hidden 和 cell 状态 - - :math:`\widetilde{c_t}` 表示候选的 cell 状态 - - :math:`i_t` ，:math:`f_t` 和 :math:`o_t` 分别为 input gate，forget gate，output gate - - :math:`W` 表示 weight （例如， :math:`W_{ix}` 是在计算 input gate :math:`i_t` 时，对输入 :math:`x_{t}` 做线性变换的 weight） - - :math:`b` 表示 bias （例如， :math:`b_{i}` 是 input gate 的 bias） - - :math:`\sigma` 表示 gate 的非线性激活函数，默认为 sigmoid - - :math:`\odot` 表示矩阵的 Hadamard product，即对两个维度相同的矩阵，将相同位置的元素相乘，得到另一个维度相同的矩阵 - -参数： - - **input** ( :ref:`api_guide_Variable` ) - LSTM的输入张量，维度为 :math:`[batch\_size, seq\_len, input\_dim]` 的 3-D Tensor，其中 seq_len 为序列的长度， input_dim 为序列词嵌入的维度。数据类型为 float32 或者 float64。 - - **init_h** ( :ref:`api_guide_Variable` ) – LSTM的初始 hidden 状态，维度为 :math:`[num\_layers, batch\_size, hidden\_size]` 的 3-D Tensor，其中 num_layers 是LSTM的总层数，hidden_size 是隐层维度。 如果is_bidirec = True， 维度应该为 :math:`[num\_layers*2, batch\_size, hidden\_size]` 。数据类型为 float32 或者 float64。 - - **init_c** ( :ref:`api_guide_Variable` ) - LSTM的初始 cell 状态。维度为 :math:`[num\_layers, batch\_size, hidden\_size]` 的 3-D Tensor，其中 num_layers 是LSTM的总层数，hidden_size 是隐层维度。 如果is_bidirec = True， 维度应该为 :math:`[num\_layers*2, batch\_size, hidden\_size]` 。数据类型为 float32 或者 float64。 - - **max_len** (int) – LSTM的最大长度。输入张量的第一个 input_dim 不能大于 max_len。 - - **hidden_size** (int) - LSTM hidden 状态的维度。 - - **num_layers** (int) – LSTM的总层数。例如，该参数设置为2，则会堆叠两个LSTM，其第一个LSTM的输出会作为第二个LSTM的输入。 - - **dropout_prob** (float，可选) – dropout比例，dropout 只在 rnn 层之间工作，而不是在时间步骤之间。dropout 不作用于最后的 rnn 层的 rnn 输出中。默认值为 0.0。 - - **is_bidirec** (bool，可选) – 是否是双向的LSTM。默认值为 False。 - - **is_test** (bool，可选) – 是否在测试阶段。默认值为 False。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - - **default_initializer** (Initializer，可选) – 用于初始化权重的初始化器，如果为None，将进行默认初始化。默认值为 None。 - - **seed** (int，可选) – LSTM中dropout的seed，如果是-1，dropout将使用随机seed。默认值为 1。 - -返回： 经过lstm运算输出的三个Tensor的tuple，包括 - -- rnn_out：LSTM hidden的输出结果的Tensor，数据类型与input一致，维度为 :math:`[batch\_size, seq\_len, hidden\_size]` 。如果 ``is_bidirec`` 设置为True，则维度为 :math:`[batch\_size, seq\_len, hidden\_size*2]` -- last_h：LSTM最后一步的hidden状态的Tensor，数据类型与input一致，维度为 :math:`[num\_layers, batch\_size, hidden\_size]` 。如果 ``is_bidirec`` 设置为True，则维度为 :math:`[num\_layers*2, batch\_size, hidden\_size]` -- last_c：LSTM最后一步的cell状态的Tensor，数据类型与input一致，维度为 :math:`[num\_layers, batch\_size, hidden\_size]` 。如果 ``is_bidirec`` 设置为True，则维度为 :math:`[num\_layers*2, batch\_size, hidden\_size]` - -返回类型: tuple（ :ref:`api_guide_Variable` , :ref:`api_guide_Variable` , :ref:`api_guide_Variable` ） - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - import paddle.fluid.layers as layers - - emb_dim = 256 - vocab_size = 10000 - data = fluid.layers.data(name='x', shape=[-1, 100, 1], - dtype='int64') - emb = fluid.layers.embedding(input=data, size=[vocab_size, emb_dim], is_sparse=True) - batch_size = 20 - max_len = 100 - dropout_prob = 0.2 - hidden_size = 150 - num_layers = 1 - init_h = layers.fill_constant( [num_layers, batch_size, hidden_size], 'float32', 0.0 ) - init_c = layers.fill_constant( [num_layers, batch_size, hidden_size], 'float32', 0.0 ) - - rnn_out, last_h, last_c = layers.lstm(emb, init_h, init_c, max_len, hidden_size, num_layers, dropout_prob=dropout_prob) - rnn_out.shape # (-1, 100, 150) - last_h.shape # (1, 20, 150) - last_c.shape # (1, 20, 150) - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/one_hot_cn.rst b/doc/paddle/api/paddle/fluid/layers/one_hot_cn.rst index fbf08df2176015fbe1a50ffef5da07e2a958089c..2aaaf117e6fc9dc5ab26032db91bef286f14e567 100644 --- a/doc/paddle/api/paddle/fluid/layers/one_hot_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/one_hot_cn.rst @@ -1,27 +1,26 @@ -.. _cn_api_fluid_one_hot: +.. _cn_api_fluid_layers_one_hot: one_hot ------------------------------- -.. py:function:: paddle.fluid.one_hot(input, depth, allow_out_of_range=False) +.. py:function:: paddle.fluid.layers.one_hot(input, depth, allow_out_of_range=False) -:alias_main: paddle.nn.functional.one_hot -:alias: paddle.nn.functional.one_hot,paddle.nn.functional.common.one_hot -:old_api: paddle.fluid.one_hot +**注意：此OP要求输入Tensor shape的最后一维必须为1。此OP将在未来的版本中被移除！推荐使用fluid.** :ref:`cn_api_fluid_one_hot` 。 + 该OP将输入（input）中的每个id转换为一个one-hot向量，其长度为 ``depth`` ，该id对应的向量维度上的值为1，其余维度的值为0。 -输出的Tensor（或LoDTensor）的shape是在输入shape的最后一维后面添加了depth的维度。 +输出的Tensor（或LoDTensor）的shape是将输入shape的最后一维替换为depth的维度。 - 示例1（allow_out_of_range=False）： .. code-block:: python 输入： - X.shape = [4] - X.data = [1, 1, 3, 0] + X.shape = [4, 1] + X.data = [[1], [1], [3], [0]] depth = 4 输出： @@ -36,8 +35,8 @@ one_hot .. code-block:: python 输入： - X.shape = [4] - X.data = [1, 1, 5, 0] + X.shape = [4, 1] + X.data = [[1], [1], [5], [0]] depth = 4 allow_out_of_range=True @@ -53,8 +52,8 @@ one_hot .. code-block:: python 输入： - X.shape = [4] - X.data = [1, 1, 5, 0] + X.shape = [4, 1] + X.data = [[1], [1], [5], [0]] depth = 4 allow_out_of_range=False @@ -63,7 +62,7 @@ one_hot 参数： - - **input** (Variable) - 维度为 :math:`[N_1, ..., N_n]` 的多维Tensor或LoDTensor，维度至少1维。数据类型为int32或int64。 + - **input** (Variable) - 维度为 :math:`[N_1, ..., N_n, 1]` 的多维Tensor或LoDTensor，维度至少两维，且最后一维必须是1。数据类型为int32或int64。 - **depth** (int) - 用于定义一个one-hot向量的长度。若输入为词id，则 ``depth`` 通常取值为词典大小。 - **allow_out_of_range** (bool) - 指明input中所包含的id值是否可以大于depth值。当超过depth时，如果 `allow_out_of_range` 为False，则会抛出 `Illegal value` 的异常；如果设置为True，该id对应的向量为0向量。默认值为False。 @@ -76,6 +75,6 @@ one_hot .. code-block:: python import paddle.fluid as fluid - # 该代码对应上述第一个示例，其中输入label的shape是[4]，输出one_hot_label的shape是[4, 4] - label = fluid.layers.data(name="label", shape=[4], append_batch_size=False, dtype="int64") - one_hot_label = fluid.one_hot(input=label, depth=4) + # 该代码对应上述第一个示例，其中输入label的shape是[4, 1]，输出one_hot_label的shape是[4, 4] + label = fluid.layers.data(name="label", shape=[4, 1], append_batch_size=False, dtype="int64") + one_hot_label = fluid.layers.one_hot(input=label, depth=4) diff --git a/doc/paddle/api/paddle/fluid/layers/ones_cn.rst b/doc/paddle/api/paddle/fluid/layers/ones_cn.rst index 4cdbac5912bfd8d9b07a97533daf43496e458b11..1eb93c5e0a86886cf3d88e93a6cea0c6e8e23e92 100644 --- a/doc/paddle/api/paddle/fluid/layers/ones_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/ones_cn.rst @@ -9,11 +9,15 @@ ones 参数： - **shape** (tuple|list|Tensor) - 输出Tensor的形状， ``shape`` 的数据类型为int32或者int64。 - - **dtype** (np.dtype|core.VarDesc.VarType|str) - 输出Tensor的数据类型，数据类型必须为float16、float32、float64、int32或int64。 + - **dtype** (np.dtype|str) - 输出Tensor的数据类型，数据类型必须为bool、 float16、float32、float64、int32或int64。 - **force_cpu** (bool， 可选) – 是否强制将输出Tensor写入CPU内存。如果 ``force_cpu`` 为False，则将输出Tensor写入当前所在运算设备的内存，默认为False。 返回：值全为1的Tensor，数据类型和 ``dtype`` 定义的类型一致。 +抛出异常： + - ``TypeError`` - 当 ``dtype`` 不是bool、 float16、float32、float64、int32、int64和None时。 + - ``TypeError`` - 当 ``shape`` 不是tuple、list、或者Tensor时， 当 ``shape`` 为Tensor，其数据类型不是int32或者int64时。 + **代码示例**： .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/layers/pad2d_cn.rst b/doc/paddle/api/paddle/fluid/layers/pad2d_cn.rst deleted file mode 100644 index 08e937f50a7eb33bb21adadc2039984ff221cf31..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/pad2d_cn.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _cn_api_fluid_layers_pad2d: - -pad2d -------------------------------- - -.. py:function:: paddle.fluid.layers.pad2d(input, paddings=[0, 0, 0, 0], mode='constant', pad_value=0.0, data_format='NCHW', name=None) - -:alias_main: paddle.nn.functional.pad2d -:alias: paddle.nn.functional.pad2d,paddle.nn.functional.common.pad2d -:old_api: paddle.fluid.layers.pad2d - - - -该OP依照 paddings 和 mode 属性对input进行2维 ``pad`` 。 - -参数： - - **input** (Variable) - 类型为float32的4-D Tensor， format为 `[N, C, H, W]` 或 `[N, H, W, C]` 。 - - **paddings** (Variable | List[int32]) - 填充大小。如果paddings是一个List，它必须包含四个整数 `[padding_top, padding_bottom, padding_left, padding_right]` 。 - 如果paddings是Variable， 则是类型为int32 的1-D Tensor，shape是 `[4]` 。默认值为 `[0,0,0,0]` 。 - - **mode** (str) - padding的三种模式，分别为 `'constant'` (默认)、 `'reflect'` 、 `'edge'` 。 `'constant'` 为填充常数 `pad_value` ， `'reflect'` 为填充以input边界值为轴的映射， `'edge'` 为填充input边界值。具体结果可见以下示例。默认值为 `'constant'` 。 - - **pad_value** (float32) - 以 `'constant'` 模式填充区域时填充的值。默认值为0.0。 - - **data_format** (str) - 指定input的format，可为 `'NCHW'` 和 `'NHWC'` ，默认值为 `'NCHW'` 。 - - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 -返回： 对input进行2维 ``pad`` 的结果，数据类型和input一样的4-D Tensor。 - -返回类型：Variable - -**示例**： - -.. code-block:: text - - Input = [[[[1., 2., 3.], - [4., 5., 6.]]]] - - Case 0: - paddings = [0, 1, 2, 3], - mode = 'constant' - pad_value = 0 - Out = [[[[0., 0., 1., 2., 3., 0., 0., 0.], - [0., 0., 4., 5., 6., 0., 0., 0.], - [0., 0., 0., 0., 0., 0., 0., 0.]]]] - - Case 1: - paddings = [0, 1, 2, 1], - mode = 'reflect' - Out = [[[[3., 2., 1., 2., 3., 2.], - [6., 5., 4., 5., 6., 5.], - [3., 2., 1., 2., 3., 2.]]]] - - Case 2: - paddings = [0, 1, 2, 1], - mode = 'edge' - Out = [[[[1., 1., 1., 2., 3., 3.], - [4., 4., 4., 5., 6., 6.], - [4., 4., 4., 5., 6., 6.]]]] - - - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.data(name='data', shape=[None, 3, 32, 32], dtype='float32') - result = fluid.layers.pad2d(input=data, paddings=[0, 1, 2, 3], mode='reflect') diff --git a/doc/paddle/api/paddle/fluid/layers/pow_cn.rst b/doc/paddle/api/paddle/fluid/layers/pow_cn.rst deleted file mode 100644 index 40eaf542138527856d25a002f16a4cf29c891f47..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/pow_cn.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _cn_api_fluid_layers_pow: - -pow -------------------------------- - -.. py:function:: paddle.pow(x, exponent, name=None) - - - - -该OP是指数激活算子： - -.. math:: - - out = x^{exponent} - -**注意：如果需要对输入进行 elementwise_pow 操作，请查使用** :ref:`cn_api_fluid_layers_elementwise_pow` 。 - -参数： - - **x** （Variable）- 多维 ``Variable``，数据类型为 ``float32`` 或 ``float64`` 。 - - **exponent** （float32|Variable）- ``float32`` 或形状为[1]的 ``Variable``，数据类型为 ``float32``。 - - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值： ``None``。 - -返回：维度与输入 `x` 相同的 ``Variable``，数据类型与 ``x`` 相同。 - -返回类型：Variable。 - - -**代码示例：** - -.. code-block:: python - - import paddle - import numpy as np - x = fluid.data(name="x", shape=[32,32], dtype="float32") - paddle.enable_imperative() - - # example 1: exponent is a float - x_data = np.array([1, 2, 3]) - exponent = 2 - x = paddle.imperative.to_variable(x_data) - res = paddle.pow(x, exponent) - print(res.numpy()) # [1 4 9] - - # example 2: exponent is a Variable - exponent = paddle.fill_constant(shape=[1], value=2, dtype='float32') - res = paddle.pow(x, exponent) - print(res.numpy()) # [1 4 9] - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/rank_cn.rst b/doc/paddle/api/paddle/fluid/layers/rank_cn.rst deleted file mode 100644 index 0d3aee591f86e84bc4a73fe40e2c31f434b558fa..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/rank_cn.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _cn_api_fluid_layers_rank: - -rank -------------------------------- - -.. py:function:: paddle.fluid.layers.rank(input) - -:alias_main: paddle.rank -:alias: paddle.rank,paddle.tensor.rank,paddle.tensor.attribute.rank -:old_api: paddle.fluid.layers.rank - - - -该OP用于计算输入Tensor的维度（秩）。 - -参数： - - **input** (Variable) — 输入input是shape为 :math:`[N_1, N_2, ..., N_k]` 的多维Tensor，数据类型可以任意类型。 - -返回：输出Tensor的秩，是一个0-D Tensor。 - -返回类型：Variable，数据类型为int32。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - input = fluid.data( - name="input", shape=[3, 100, 100], dtype="float32") - rank = fluid.layers.rank(input) # rank=(4,) - - diff --git a/doc/paddle/api/paddle/fluid/layers/rank_loss_cn.rst b/doc/paddle/api/paddle/fluid/layers/rank_loss_cn.rst deleted file mode 100644 index 3f6f5b2a83df84fa477006499891176be909b1bf..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/rank_loss_cn.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _cn_api_fluid_layers_rank_loss: - -rank_loss -------------------------------- - -.. py:function:: paddle.fluid.layers.rank_loss(label, left, right, name=None) - -:alias_main: paddle.nn.functional.rank_loss -:alias: paddle.nn.functional.rank_loss,paddle.nn.functional.loss.rank_loss -:old_api: paddle.fluid.layers.rank_loss - - - -该OP实现了RankNet模型中的排序损失层。RankNet是一种文档对（pairwise）排序模型，训练样本由一对文档（假设用A、B来表示）组成。标签（假设用P来表示）表示A的排名是否高于B。更多详情请参考：`RankNet `_ - -排序损失层有三个输入： :math:`o_i` 、 :math:`o_j` 和 :math:`\tilde{P_{ij}}` ，输入分别表示RankNet模型对文档A、B的输出得分和标签P的值；排序损失层的输入是批输入数据（批大小大于等于1）；标签P的取值可以为： {0, 1} 或 {0, 0.5, 1} ，其中，0.5表示输入文档对排序相同。输入数据的排序损失 :math:`C_{i,j}` 计算过程如下： - -.. math:: - - C_{i,j} &= -\tilde{P_{ij}} * o_{i,j} + \log(1 + e^{o_{i,j}}) - - o_{i,j} &= o_i - o_j - - \tilde{P_{i,j}} &= \left \{0, 0.5, 1 \right \} \ or \ \left \{0, 1 \right \} - -参数： - - **label** (Variable)：维度为 :math:`[batch,1]` 的2-D ``Tensor`` ，数据类型为float32。其中batch表示批数据的大小。表示A的排名是否高于B。 - - **left** (Variable)：维度为 :math:`[batch,1]` 的2-D ``Tensor`` ，数据类型为float32。其中batch表示批数据的大小。表示RankNet对文档A的输出得分。 - - **right** (Variable)：维度为 :math:`[batch,1]` 的2-D ``Tensor`` ，数据类型为float32。其中batch表示批数据的大小。表示RankNet对文档B的输出得分。 - - **name** (str, 可选)：具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回：表示排序损失层输出值的 ``Tensor`` ，数据类型为float32，返回值维度为 :math:`[batch,1]` 。 - -返回类型：Variable - -抛出异常： - - ``ValueError`` - 输入 ``label`` ， ``left`` ，和 ``right`` 至少有一个不是 ``Variable`` 类型。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - label = fluid.layers.data(name="label", shape=[-1, 1], dtype="float32") - left = fluid.layers.data(name="left", shape=[-1, 1], dtype="float32") - right = fluid.layers.data(name="right", shape=[-1, 1], dtype="float32") - out = fluid.layers.rank_loss(label, left, right) - diff --git a/doc/paddle/api/paddle/fluid/layers/reduce_prod_cn.rst b/doc/paddle/api/paddle/fluid/layers/reduce_prod_cn.rst index a1b65ee1ddb2fe5e59e63df68d7a674a684d6e65..c0a11bc9204a431a4fba0df588189b9d604dcf97 100644 --- a/doc/paddle/api/paddle/fluid/layers/reduce_prod_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/reduce_prod_cn.rst @@ -15,7 +15,7 @@ reduce_prod 参数： - **input** （Variable）- 输入变量为多维Tensor或LoDTensor，支持数据类型为float32，float64，int32，int64。 - - **dim** （list | int ，可选）- 求乘积运算的维度。如果为None，则计算所有元素的乘积并返回包含单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将变为 :math:`rank+dim[i]` ，默认值为None。 + - **dim** （int|list|tuple ，可选）- 求乘积运算的维度。如果为None，则计算所有元素的乘积并返回包含单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将变为 :math:`rank+dim[i]` ，默认值为None。 - **keep_dim** （bool）- 是否在输出Tensor中保留减小的维度。如 keep_dim 为true，否则结果张量的维度将比输入张量小，默认值为False。 - **name** （str ， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 diff --git a/doc/paddle/api/paddle/fluid/layers/reshape_cn.rst b/doc/paddle/api/paddle/fluid/layers/reshape_cn.rst deleted file mode 100644 index a5e39dff07f19832e9468f7deea5cc43b366a33d..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/reshape_cn.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _cn_api_fluid_layers_reshape: - -reshape -------------------------------- - -.. py:function:: paddle.fluid.layers.reshape(x, shape, actual_shape=None, act=None, inplace=False, name=None) - -:alias_main: paddle.reshape -:alias: paddle.reshape,paddle.tensor.reshape,paddle.tensor.manipulation.reshape -:old_api: paddle.fluid.layers.reshape - - - -该OP在保持输入 ``x`` 数据不变的情况下，改变 ``x`` 的形状。 - -目标形状可由 ``shape`` 或 ``actual_shape`` 给出。当两个属性同时被指定时，``actual_shape`` 的优先级高于 ``shape`` ，但此时 ``shape`` 只能是整数列表或元组，且在编译时仍然应该正确地设置 ``shape`` 以保证形状推断。 - -在指定目标shape时存在一些技巧： - -.. code-block:: text - - 1. -1 表示这个维度的值是从x的元素总数和剩余维度推断出来的。因此，有且只有一个维度可以被设置为-1。 - 2. 0 表示实际的维数是从x的对应维数中复制出来的，因此shape中0的索引值不能超过x的维度。 - - -这里有一些例子来解释它们： - -.. code-block:: text - - 1. 给定一个形状为[2,4,6]的三维张量x，目标形状为[6,8]，则将x变换为形状为[6,8]的2-D张量，且x的数据保持不变。 - 2. 给定一个形状为[2,4,6]的三维张量x，目标形状为[2,3,-1,2]，则将x变换为形状为[2,3,4,2]的4-D张量，且x的数据保持不变。在这种情况下，目标形状的一个维度被设置为-1，这个维度的值是从x的元素总数和剩余维度推断出来的。 - 3. 给定一个形状为[2,4,6]的三维张量x，目标形状为[-1,0,3,2]，则将x变换为形状为[2,4,3,2]的4-D张量，且x的数据保持不变。在这种情况下，0对应位置的维度值将从x的对应维数中复制,-1对应位置的维度值由x的元素总数和剩余维度推断出来。 - -**注意：参数** ``actual_shape`` **之后将被舍弃，只用参数** ``shape`` **来表示目标形状。** - -参数： - - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor``，数据类型为 ``float32``，``float64``，``int32``，或 ``int64``。 - - **shape** （list|tuple|Variable）- 数据类型是 ``int32`` 。定义目标形状。目标形状最多只能有一个维度为-1。如果 ``shape`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[1]的 ``Tensor`` 或 ``LoDTensor``。如果 ``shape`` 的类型是 ``Variable``，则是1-D的 ``Tensor`` 或 ``LoDTensor``。 - - **actual_shape** （Variable，可选）- 1-D ``Tensor`` 或 ``LoDTensor``，默认值：`None`。如果 ``actual_shape`` 被提供，``actual_shape`` 具有比 ``shape`` 更高的优先级，此时 ``shape`` 只能是整数列表或元组。更新提示：``actual_shape`` 在未来的版本中将被舍弃，并用 ``shape`` 代替。 - - **act** （str，可选）- 对形状改变后的输入变量做非线性激活操作，激活函数类型可以参考 :ref:`api_guide_activations` 。默认值： ``None``。 - - **inplace** （bool，可选）- 如果 ``inplace`` 为 ``True``，则 ``layers.reshape`` 的输入和输出是同一个变量，否则 ``layers.reshape`` 的输入和输出是不同的变量。默认值：``False``。请注意，如果 ``x`` 是多个OP的输入，则 ``inplace`` 必须为False。 - - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值： ``None``。 - -返回：多维 ``Tensor`` 或 ``LoDTensor``，数据类型与 ``input`` 相同。如果 ``inplace`` 为 ``False``，则返回一个新的变量，否则将改变输入变量 ``x`` 自身。如果 ``act`` 为 ``None``，则直接返回形状改变后的变量，否则返回经过激活函数后的变量。 - -返回类型：Variable。 - -抛出异常： - - :code:`TypeError`：``actual_shape`` 的类型应该是 Variable 或 None。 - - :code:`TypeError`：``starts`` 的类型应该是list、tuple 或 Variable。 - - :code:`ValueError`：``shape`` 中至多有一个元素可以是-1。 - - :code:`ValueError`：``shape`` 中的元素为0时，对应的维度应该小于等于``x``的维度。 - - :code:`ValueError`：``shape`` 中的元素除了-1之外，都应该是非负值。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - # example 1: - # attr shape is a list which doesn't contain tensor Variable. - data_1 = fluid.data( - name='data_1', shape=[2, 4, 6], dtype='float32') - reshaped_1 = fluid.layers.reshape( - x=data_1, shape=[-1, 0, 3, 2], inplace=True) - # the shape of reshaped_1 is [2,4,3,2]. - - # example 2: - # attr shape is a list which contains tensor Variable. - data_2 = fluid.layers.fill_constant([2,25], "int32", 3) - dim = fluid.layers.fill_constant([1], "int32", 5) - reshaped_2 = fluid.layers.reshape(data_2, shape=[dim, 10]) - # the shape of reshaped_2 is [5,10]. - - # example 3: - data_3 = fluid.data( - name="data_3", shape=[2,4,6], dtype='float32') - reshaped_3 = fluid.layers.reshape(x=data_3, shape=[6,8]) - # the shape of reshaped_3 is [6,8]. - - - - - - - - diff --git a/doc/paddle/api/paddle/fluid/layers/sequence_mask_cn.rst b/doc/paddle/api/paddle/fluid/layers/sequence_mask_cn.rst deleted file mode 100644 index ac7fafb2faa1728201dc7452da644c8449a6f728..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/sequence_mask_cn.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _cn_api_fluid_layers_sequence_mask: - -sequence_mask -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_mask(x, maxlen=None, dtype='int64', name=None) - - - - -该层根据输入 ``x`` 和 ``maxlen`` 输出一个掩码，数据类型为 ``dtype`` 。 - -假设 x 是一个形状为 ``[d_1, d_2，…, d_n]`` 的张量， 则输出 y 是一个形状为 ``[d_1, d_2，… ，d_n, maxlen]`` 的掩码，其中: - -.. math:: - - y(i_1, i_2,..., i_n, j) = (j < x(i_1, i_2,..., i_n)) - -范例如下： - -:: - - 给定输入： - x = [3, 1, 1, 0] maxlen = 4 - - 得到输出张量： - mask = [[1, 1, 1, 0], - [1, 0, 0, 0], - [1, 0, 0, 0], - [0, 0, 0, 0]] - - - - - -参数： - - **x** (Variable) - 输入张量，其元素是小于等于 ``maxlen`` 的整数，形状为 ``[d_1, d_2，…, d_n]`` 的Tensor或LoDTensor。 - - **maxlen** (int，可选) - 序列的最大长度。默认为空，此时 ``maxlen`` 取 ``x`` 中所有元素的最大值。 - - **dtype** (np.dtype|core.VarDesc.VarType|str，可选) - 输出的数据类型，默认为 ``int64`` 。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回： mask张量，Tensor或LoDTensor，形状为 ``[d_1, d_2，… ，d_n, maxlen]`` ，数据类型由 ``dtype`` 指定，支持float32、float64、int32和int64，默认为int64。 - -返回类型： Variable - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - import paddle.fluid.layers as layers - - x = fluid.data(name='x', shape=[10], dtype='float32', lod_level=1) - mask = layers.sequence_mask(x=x) - - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/activation/sigmoid_cn.rst b/doc/paddle/api/paddle/fluid/layers/sigmoid_cn.rst similarity index 100% rename from doc/paddle/api/paddle/nn/functional/activation/sigmoid_cn.rst rename to doc/paddle/api/paddle/fluid/layers/sigmoid_cn.rst diff --git a/doc/paddle/api/paddle/fluid/layers/sign_cn.rst b/doc/paddle/api/paddle/fluid/layers/sign_cn.rst index 5559e7a7bef67ed07aa58e3162e6c501867a803f..7b5e84aa970e7c8dd9c736990c7f32f5d8e7fc17 100644 --- a/doc/paddle/api/paddle/fluid/layers/sign_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/sign_cn.rst @@ -5,12 +5,6 @@ sign .. py:function:: paddle.fluid.layers.sign(x) -:alias_main: paddle.sign -:alias: paddle.sign,paddle.tensor.sign,paddle.tensor.math.sign -:old_api: paddle.fluid.layers.sign - - - 此OP对输入x中每个元素进行正负判断，并且输出正负判断值：1代表正，-1代表负，0代表零。 参数： diff --git a/doc/paddle/api/paddle/fluid/layers/slice_cn.rst b/doc/paddle/api/paddle/fluid/layers/slice_cn.rst old mode 100644 new mode 100755 index ed77cc9498273ed264dd97a052fd35c1327a647a..4c2214100e77940abb473fa8d5b148187a3a8176 --- a/doc/paddle/api/paddle/fluid/layers/slice_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/slice_cn.rst @@ -34,7 +34,7 @@ slice 参数： - **input** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor``，数据类型为 ``float16``， ``float32``，``float64``，``int32``，或 ``int64``。 - - **axes** （list|tuple）- 数据类型是 ``int32``。表示进行切片的轴。它是可选的，如果不存在，将被视为 :math:`[0,1，...，len（starts）- 1]`。 + - **axes** （list|tuple）- 数据类型是 ``int32``。表示进行切片的轴。 - **starts** （list|tuple|Variable）- 数据类型是 ``int32``。如果 ``starts`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[1]的 ``Tensor`` 或 ``LoDTensor``。如果 ``starts`` 的类型是 ``Variable``，则是1-D ``Tensor`` 或 ``LoDTensor``。表示在各个轴上切片的起始索引值。 - **ends** （list|tuple|Variable）- 数据类型是 ``int32``。如果 ``ends`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[1]的 ``Tensor`` 或 ``LoDTensor``。如果 ``ends`` 的类型是 ``Variable``，则是1-D ``Tensor`` 或 ``LoDTensor``。表示在各个轴上切片的结束索引值。 @@ -45,7 +45,6 @@ slice 抛出异常： - :code:`TypeError`：``starts`` 的类型应该是 list、tuple 或 Variable。 - :code:`TypeError`：``ends`` 的类型应该是 list、tuple 或 Variable。 - **代码示例：** .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/layers/softmax_cn.rst b/doc/paddle/api/paddle/fluid/layers/softmax_cn.rst index a11f955072ab19183abde10ce55469e81bc1c696..21052f227cd42db24536fd67b97c77cb6bdc5057 100755 --- a/doc/paddle/api/paddle/fluid/layers/softmax_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/softmax_cn.rst @@ -5,12 +5,6 @@ softmax .. py:function:: paddle.fluid.layers.softmax(input, use_cudnn=False, name=None, axis=-1) -:alias_main: paddle.nn.functional.softmax -:alias: paddle.nn.functional.softmax,paddle.nn.functional.activation.softmax -:old_api: paddle.fluid.layers.softmax - - - 该OP实现了softmax层。OP的计算过程如下： 步骤1：输入 ``input`` 的 ``axis`` 维会被置换到最后一维； diff --git a/doc/paddle/api/paddle/fluid/layers/split_cn.rst b/doc/paddle/api/paddle/fluid/layers/split_cn.rst index ca1607ee55c07488cd3a343ec72bf5c216ae2614..260756ee823d1b3c341d7f1da5ecf631f692dff4 100644 --- a/doc/paddle/api/paddle/fluid/layers/split_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/split_cn.rst @@ -19,11 +19,6 @@ split 返回：分割后的Tensor列表。 -抛出异常： - - :code:`TypeError`：``input`` 的数据类型不是bool、float16、float32、float64、int32或int64时 。 - - :code:`TypeError`：``num_or_sections`` 不是int、list 或 tuple时。 - - :code:`TypeError`：``dim`` 不是 int 或 Tensor时。当 ``dim`` 为Tensor，其数据类型不是int32或int64时。 - **代码示例**： .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/layers/unbind_cn.rst b/doc/paddle/api/paddle/fluid/layers/unbind_cn.rst deleted file mode 100644 index 1ed191175d7e85592225ffc3c19c8faeda8c83d2..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/layers/unbind_cn.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _cn_api_paddle_tensor_unbind -unbind -------------------------------- - -.. py:function:: paddle.tensor.unbind(input, axis=0) - -:alias_main: paddle.unbind -:alias: paddle.unbind,paddle.tensor.unbind,paddle.tensor.manipulation.unbind - - - -该OP将输入Tensor按照指定的维度分割成多个子Tensor。 - -**参数**： - - **input** (Variable) - 输入变量，数据类型为float32，float64，int32，int64的多维Tensor。 - - **axis** (int32|int64，可选) - 数据类型为int32或int64,表示需要分割的维度。如果axis < 0，则划分的维度为rank(input) + axis。默认值为0。 - -**返回**：分割后的Tensor列表。 - -**返回类型**：列表(Variable)，数据类型为int32，int64，float32，float64。 - -**代码示例**： - -.. code-block:: python - - import paddle - # input is a variable which shape is [3, 4, 5] - input = paddle.fluid.data( - name="input", shape=[3, 4, 5], dtype="float32") - [x0, x1, x2] = paddle.tensor.unbind(input, axis=0) - # x0.shape [4, 5] - # x1.shape [4, 5] - # x2.shape [4, 5] - [x0, x1, x2, x3] = paddle.tensor.unbind(input, axis=1) - # x0.shape [3, 5] - # x1.shape [3, 5] - # x2.shape [3, 5] - # x3.shape [3, 5] diff --git a/doc/paddle/api/paddle/fluid/layers/unique_cn.rst b/doc/paddle/api/paddle/fluid/layers/unique_cn.rst index 0877f8686aa1101fff05377404492f8d45aa493f..362d511d8b2253fcfd9241f9da9b060420cbd8bf 100644 --- a/doc/paddle/api/paddle/fluid/layers/unique_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/unique_cn.rst @@ -5,17 +5,11 @@ unique .. py:function:: paddle.fluid.layers.unique(x, dtype='int32') -:alias_main: paddle.unique -:alias: paddle.unique,paddle.tensor.unique,paddle.tensor.manipulation.unique -:old_api: paddle.fluid.layers.unique - - - unique为 ``x`` 返回一个unique张量和一个指向该unique张量的索引。 参数： - - **x** (Variable) - 一个1维输入张量 - - **dtype** (np.dtype|core.VarDesc.VarType|str) – 索引张量的类型，int32，int64。 + - **x** (Tensor) - 一个1维输入张量 + - **dtype** (np.dtype|str, 可选) – 索引张量的类型，应该为int32或者int64。默认：int32. 返回：元组(out, index)。 ``out`` 为 ``x`` 的指定dtype的unique张量, ``index`` 是一个指向 ``out`` 的索引张量, 用户可以通过该函数来转换原始的 ``x`` 张量的索引。 diff --git a/doc/paddle/api/paddle/fluid/layers/unstack_cn.rst b/doc/paddle/api/paddle/fluid/layers/unstack_cn.rst index cc4324c6b5764b7a03cfe509345e14aa43e505ee..00b8cfe97a1409bc9b845690ba7ec3dd29a77c86 100644 --- a/doc/paddle/api/paddle/fluid/layers/unstack_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/unstack_cn.rst @@ -14,7 +14,7 @@ unstack 该OP将单个dim为 ``D`` 的Tensor沿 ``axis`` 轴unpack为 ``num`` 个dim为 ``(D-1)`` 的Tensor 参数: - - **x** (Variable) – 输入x为 ``dim > 0`` 的Tensor， + - **x** (Tensor) – 输入x为 ``dim > 0`` 的Tensor， 支持的数据类型: float32，float64，int32，int64。 - **axis** (int | 可选) – 输入Tensor进行unpack运算所在的轴，axis的范围为：``[-D, D)`` ， @@ -24,7 +24,7 @@ unstack 返回: 长度为num的Tensor列表, 数据类型与输入Tensor相同，dim为 ``(D-1)``。 -返回类型: list(Variable) +返回类型: list(Tensor) 抛出异常： - :code:`ValueError`：``x.shape[axis]`` <= 0 或 ``axis`` 不在[-D, D)范围内 @@ -34,7 +34,7 @@ unstack .. code-block:: python import paddle.fluid as fluid - x = fluid.layers.data(name='x', shape=[2, 3, 5], dtype='float32') #创建一个shape=[2, 3, 5]的Tensor + x = fluid.data(name='x', shape=[2, 3, 5], dtype='float32') #创建一个shape=[2, 3, 5]的Tensor y = fluid.layers.unstack(x, axis=1) #沿着第1轴进行unpack, unpack后为3个shape=[2，5]的Tensor diff --git a/doc/paddle/api/paddle/fluid/layers/zeros_cn.rst b/doc/paddle/api/paddle/fluid/layers/zeros_cn.rst index 83801e7ff64ca8536f1f68b5afb435884ab4a8d8..170007734a9e5e7aa4acd541c032f55bc96cb058 100644 --- a/doc/paddle/api/paddle/fluid/layers/zeros_cn.rst +++ b/doc/paddle/api/paddle/fluid/layers/zeros_cn.rst @@ -9,11 +9,15 @@ zeros 参数： - **shape** (tuple|list|Tensor) - 输出Tensor的形状， ``shape`` 的数据类型为int32或者int64。 - - **dtype** (np.dtype|core.VarDesc.VarType|str) - 输出Tensor的数据类型，数据类型必须为float16、float32、float64、int32或int64。 + - **dtype** (np.dtype|str) - 输出Tensor的数据类型，数据类型必须为bool、 float16、float32、float64、int32或int64。 - **force_cpu** (bool， 可选) - 是否强制将输出Tensor写入CPU内存。如果 ``force_cpu`` 为False，则将输出Tensor写入当前所在运算设备的内存，默认为False。 返回：值全为0的Tensor，数据类型和 ``dtype`` 定义的类型一致。 +抛出异常： + - ``TypeError`` - 当 ``dtype`` 不是bool、 float16、float32、float64、int32、int64。 + - ``TypeError`` - 当 ``shape`` 不是tuple、list、或者Tensor时。 当 ``shape`` 为Tensor，其数据类型不是int32或者int64时。 + **代码示例**： .. code-block:: python diff --git a/doc/paddle/api/paddle/fluid/memory_optimize_cn.rst b/doc/paddle/api/paddle/fluid/memory_optimize_cn.rst index bc95cc3995e565d50cc846d613d449bb89d6e936..d9a5a2b023fc6f1d578d254b5057a9c01d6940b9 100644 --- a/doc/paddle/api/paddle/fluid/memory_optimize_cn.rst +++ b/doc/paddle/api/paddle/fluid/memory_optimize_cn.rst @@ -1,14 +1,13 @@ -.. _cn_api_fluid_memory_optimize: +.. _cn_api_fluid_transpiler_memory_optimize: memory_optimize ------------------------------- -.. py:function:: paddle.fluid.memory_optimize(input_program, skip_opt_set=None, print_log=False, level=0, skip_grads=True) +.. py:function:: paddle.fluid.transpiler.memory_optimize(input_program, skip_opt_set=None, print_log=False, level=0, skip_grads=True) :api_attr: 声明式编程模式（静态图) -**从1.6版本开始此接口不再推荐使用，请不要在新写的代码中使用它，1.6+版本已默认开启更优的存储优化策略** - +**从1.6版本开始此接口不再推荐使用，请不要在新写的代码中使用它，1.6+版本已默认开启更优的存储优化策略** \ No newline at end of file diff --git a/doc/paddle/api/paddle/fluid/metrics/Accuracy_cn.rst b/doc/paddle/api/paddle/fluid/metrics/Accuracy_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..0cb6ea087033b21afd2cea5838f6d1366868b92f --- /dev/null +++ b/doc/paddle/api/paddle/fluid/metrics/Accuracy_cn.rst @@ -0,0 +1,63 @@ +.. _cn_api_fluid_metrics_Accuracy: + +Accuracy +------------------------------- +.. py:class:: paddle.fluid.metrics.Accuracy(name=None) + + + + +该接口用来计算多个mini-batch的平均准确率。Accuracy对象有两个状态value和weight。Accuracy的定义参照 https://en.wikipedia.org/wiki/Accuracy_and_precision 。 + +参数: + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：初始化后的 ``Accuracy`` 对象 + +返回类型：Accuracy + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + # 假设有batch_size = 128 + batch_size=128 + accuracy_manager = fluid.metrics.Accuracy() + # 假设第一个batch的准确率为0.9 + batch1_acc = 0.9 + accuracy_manager.update(value = batch1_acc, weight = batch_size) + print("expect accuracy: %.2f, get accuracy: %.2f" % (batch1_acc, accuracy_manager.eval())) + # 假设第二个batch的准确率为0.8 + batch2_acc = 0.8 + accuracy_manager.update(value = batch2_acc, weight = batch_size) + #batch1和batch2的联合准确率为(batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2 + print("expect accuracy: %.2f, get accuracy: %.2f" % ((batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2, accuracy_manager.eval())) + #重置accuracy_manager + accuracy_manager.reset() + #假设第三个batch的准确率为0.8 + batch3_acc = 0.8 + accuracy_manager.update(value = batch3_acc, weight = batch_size) + print("expect accuracy: %.2f, get accuracy: %.2f" % (batch3_acc, accuracy_manager.eval())) + +.. py:method:: update(value, weight) + +该函数使用输入的(value, weight)来累计更新Accuracy对象的对应状态，更新方式如下： + + .. math:: + \\ \begin{array}{l}{\text { self. value }+=\text { value } * \text { weight }} \\ {\text { self. weight }+=\text { weight }}\end{array} \\ + +参数： + - **value** (float|numpy.array) – mini-batch的正确率 + - **weight** (int|float) – mini-batch的大小 + +返回：无 + +.. py:method:: eval() + +该函数计算并返回累计的mini-batches的平均准确率。 + +返回：累计的mini-batches的平均准确率 + +返回类型：float或numpy.array + diff --git a/doc/paddle/api/paddle/fluid/metrics/Auc_cn.rst b/doc/paddle/api/paddle/fluid/metrics/Auc_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..8e6b7bfea5ec381b7af051ba39fc080291b4fcba --- /dev/null +++ b/doc/paddle/api/paddle/fluid/metrics/Auc_cn.rst @@ -0,0 +1,67 @@ +.. _cn_api_fluid_metrics_Auc: + +Auc +------------------------------- +.. py:class:: paddle.fluid.metrics.Auc(name, curve='ROC', num_thresholds=4095) + + + + +**注意**：目前只用Python实现Auc，可能速度略慢 + +该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。 + +该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。 + +参数： + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + - **curve** (str) - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。 + +返回：初始化后的 ``Auc`` 对象 + +返回类型：Auc + +**代码示例**： + +.. code-block:: python + + import paddle.fluid as fluid + import numpy as np + # 初始化auc度量 + auc_metric = fluid.metrics.Auc("ROC") + + # 假设batch_size为128 + batch_num = 100 + batch_size = 128 + + for batch_id in range(batch_num): + + class0_preds = np.random.random(size = (batch_size, 1)) + class1_preds = 1 - class0_preds + + preds = np.concatenate((class0_preds, class1_preds), axis=1) + + labels = np.random.randint(2, size = (batch_size, 1)) + auc_metric.update(preds = preds, labels = labels) + + # 应为一个接近0.5的值，因为preds是随机指定的 + print("auc for iteration %d is %.2f" % (batch_id, auc_metric.eval())) + +.. py:method:: update(preds, labels) + +用给定的预测值和标签更新Auc曲线。 + +参数： + - **preds** (numpy.array) - 维度为[batch_size, 2]，preds[i][j]表示将实例i划分为类别j的概率。 + - **labels** (numpy.array) - 维度为[batch_size, 1]，labels[i]为0或1，代表实例i的标签。 + +返回：无 + +.. py:method:: eval() + +该函数计算并返回Auc值。 + +返回：Auc值 + +返回类型：float + diff --git a/doc/paddle/api/paddle/metric/ChunkEvaluator_cn.rst b/doc/paddle/api/paddle/fluid/metrics/ChunkEvaluator_cn.rst similarity index 100% rename from doc/paddle/api/paddle/metric/ChunkEvaluator_cn.rst rename to doc/paddle/api/paddle/fluid/metrics/ChunkEvaluator_cn.rst diff --git a/doc/paddle/api/paddle/metric/CompositeMetric_cn.rst b/doc/paddle/api/paddle/fluid/metrics/CompositeMetric_cn.rst similarity index 100% rename from doc/paddle/api/paddle/metric/CompositeMetric_cn.rst rename to doc/paddle/api/paddle/fluid/metrics/CompositeMetric_cn.rst diff --git a/doc/paddle/api/paddle/metric/DetectionMAP_cn.rst b/doc/paddle/api/paddle/fluid/metrics/DetectionMAP_cn.rst similarity index 100% rename from doc/paddle/api/paddle/metric/DetectionMAP_cn.rst rename to doc/paddle/api/paddle/fluid/metrics/DetectionMAP_cn.rst diff --git a/doc/paddle/api/paddle/metric/EditDistance_cn.rst b/doc/paddle/api/paddle/fluid/metrics/EditDistance_cn.rst similarity index 100% rename from doc/paddle/api/paddle/metric/EditDistance_cn.rst rename to doc/paddle/api/paddle/fluid/metrics/EditDistance_cn.rst diff --git a/doc/paddle/api/paddle/fluid/metrics/Precision_cn.rst b/doc/paddle/api/paddle/fluid/metrics/Precision_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..29a1cb89a9ebc7185c8ddb596fe8e1494ece800d --- /dev/null +++ b/doc/paddle/api/paddle/fluid/metrics/Precision_cn.rst @@ -0,0 +1,62 @@ +.. _cn_api_fluid_metrics_Precision: + +Precision +------------------------------- + +.. py:class:: paddle.fluid.metrics.Precision(name=None) + + + + +精确率Precision(也称为 positive predictive value,正预测值)是被预测为正样例中实际为正的比例。 https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers 该类管理二分类任务的precision分数。 + + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + import numpy as np + + metric = fluid.metrics.Precision() + + # 生成预测值和标签 + + preds = [[0.1], [0.7], [0.8], [0.9], [0.2], + [0.2], [0.3], [0.5], [0.8], [0.6]] + + labels = [[0], [1], [1], [1], [1], + [0], [0], [0], [0], [0]] + + preds = np.array(preds) + labels = np.array(labels) + + metric.update(preds=preds, labels=labels) + precision = metric.eval() + + print("expected precision: %.2f and got %.2f" % ( 3.0 / 5.0, precision)) + + + +.. py:method:: update(preds, labels) + +使用当前mini-batch的预测结果更新精确率的计算。 + +参数: + - **preds** (numpy.array) - 当前mini-batch的预测结果，二分类sigmoid函数的输出，shape为[batch_size, 1]，数据类型为'float64'或'float32'。 + - **labels** (numpy.array) - 当前mini-batch的真实标签，输入的shape应与preds保持一致，shape为[batch_size, 1]，数据类型为'int32'或'int64' + +返回：无 + + + +.. py:method:: eval() + +计算出最终的精确率。 + +参数：无 + +返回: 精确率的计算结果。标量输出，float类型 +返回类型：float + + diff --git a/doc/paddle/api/paddle/fluid/metrics/Recall_cn.rst b/doc/paddle/api/paddle/fluid/metrics/Recall_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..3d4975fc55e42f251e983fd551c760511407f003 --- /dev/null +++ b/doc/paddle/api/paddle/fluid/metrics/Recall_cn.rst @@ -0,0 +1,71 @@ +.. _cn_api_fluid_metrics_Recall: + +Recall +------------------------------- + +.. py:class:: paddle.fluid.metrics.Recall(name=None) + + + + +召回率Recall（也称为敏感度）是指得到的相关实例数占相关实例总数的比例。https://en.wikipedia.org/wiki/Precision_and_recall 该类管理二分类任务的召回率。 + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + import numpy as np + + metric = fluid.metrics.Recall() + # 生成预测值和标签 + preds = [[0.1], [0.7], [0.8], [0.9], [0.2], + [0.2], [0.3], [0.5], [0.8], [0.6]] + labels = [[0], [1], [1], [1], [1], + [0], [0], [0], [0], [0]] + + preds = np.array(preds) + labels = np.array(labels) + + metric.update(preds=preds, labels=labels) + recall = metric.eval() + + print("expected recall: %.2f and got %.2f" % ( 3.0 / 4.0, recall)) + + + +.. py:method:: update(preds, labels) + +使用当前mini-batch的预测结果更新召回率的计算。 + +参数： + - **preds** (numpy.array) - 当前mini-batch的预测结果，二分类sigmoid函数的输出，shape为[batch_size, 1]，数据类型为'float64'或'float32'。 + - **labels** (numpy.array) - 当前mini-batch的真实标签，输入的shape应与preds保持一致，shape为[batch_size, 1]，数据类型为'int32'或'int64' + +返回：无 + + + +.. py:method:: eval() + +计算出最终的召回率。 + +参数：无 + +返回：召回率的计算结果。标量输出，float类型 +返回类型：float + + + + + + + + + + + + + + + diff --git a/doc/paddle/api/paddle/fluid/one_hot_cn.rst b/doc/paddle/api/paddle/fluid/one_hot_cn.rst index fbf08df2176015fbe1a50ffef5da07e2a958089c..2aaaf117e6fc9dc5ab26032db91bef286f14e567 100644 --- a/doc/paddle/api/paddle/fluid/one_hot_cn.rst +++ b/doc/paddle/api/paddle/fluid/one_hot_cn.rst @@ -1,27 +1,26 @@ -.. _cn_api_fluid_one_hot: +.. _cn_api_fluid_layers_one_hot: one_hot ------------------------------- -.. py:function:: paddle.fluid.one_hot(input, depth, allow_out_of_range=False) +.. py:function:: paddle.fluid.layers.one_hot(input, depth, allow_out_of_range=False) -:alias_main: paddle.nn.functional.one_hot -:alias: paddle.nn.functional.one_hot,paddle.nn.functional.common.one_hot -:old_api: paddle.fluid.one_hot +**注意：此OP要求输入Tensor shape的最后一维必须为1。此OP将在未来的版本中被移除！推荐使用fluid.** :ref:`cn_api_fluid_one_hot` 。 + 该OP将输入（input）中的每个id转换为一个one-hot向量，其长度为 ``depth`` ，该id对应的向量维度上的值为1，其余维度的值为0。 -输出的Tensor（或LoDTensor）的shape是在输入shape的最后一维后面添加了depth的维度。 +输出的Tensor（或LoDTensor）的shape是将输入shape的最后一维替换为depth的维度。 - 示例1（allow_out_of_range=False）： .. code-block:: python 输入： - X.shape = [4] - X.data = [1, 1, 3, 0] + X.shape = [4, 1] + X.data = [[1], [1], [3], [0]] depth = 4 输出： @@ -36,8 +35,8 @@ one_hot .. code-block:: python 输入： - X.shape = [4] - X.data = [1, 1, 5, 0] + X.shape = [4, 1] + X.data = [[1], [1], [5], [0]] depth = 4 allow_out_of_range=True @@ -53,8 +52,8 @@ one_hot .. code-block:: python 输入： - X.shape = [4] - X.data = [1, 1, 5, 0] + X.shape = [4, 1] + X.data = [[1], [1], [5], [0]] depth = 4 allow_out_of_range=False @@ -63,7 +62,7 @@ one_hot 参数： - - **input** (Variable) - 维度为 :math:`[N_1, ..., N_n]` 的多维Tensor或LoDTensor，维度至少1维。数据类型为int32或int64。 + - **input** (Variable) - 维度为 :math:`[N_1, ..., N_n, 1]` 的多维Tensor或LoDTensor，维度至少两维，且最后一维必须是1。数据类型为int32或int64。 - **depth** (int) - 用于定义一个one-hot向量的长度。若输入为词id，则 ``depth`` 通常取值为词典大小。 - **allow_out_of_range** (bool) - 指明input中所包含的id值是否可以大于depth值。当超过depth时，如果 `allow_out_of_range` 为False，则会抛出 `Illegal value` 的异常；如果设置为True，该id对应的向量为0向量。默认值为False。 @@ -76,6 +75,6 @@ one_hot .. code-block:: python import paddle.fluid as fluid - # 该代码对应上述第一个示例，其中输入label的shape是[4]，输出one_hot_label的shape是[4, 4] - label = fluid.layers.data(name="label", shape=[4], append_batch_size=False, dtype="int64") - one_hot_label = fluid.one_hot(input=label, depth=4) + # 该代码对应上述第一个示例，其中输入label的shape是[4, 1]，输出one_hot_label的shape是[4, 4] + label = fluid.layers.data(name="label", shape=[4, 1], append_batch_size=False, dtype="int64") + one_hot_label = fluid.layers.one_hot(input=label, depth=4) diff --git a/doc/paddle/api/paddle/fluid/optimizer/AdamOptimizer_cn.rst b/doc/paddle/api/paddle/fluid/optimizer/AdamOptimizer_cn.rst deleted file mode 100644 index 8e07f80b205f836e3d08f5af4989d6246e988769..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/optimizer/AdamOptimizer_cn.rst +++ /dev/null @@ -1,289 +0,0 @@ -.. _cn_api_fluid_optimizer_AdamOptimizer: - -AdamOptimizer -------------------------------- - -.. py:class:: paddle.fluid.optimizer.AdamOptimizer(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameter_list=None, regularization=None, grad_clip=None, name=None, lazy_mode=False) - - - - -Adam优化器出自 `Adam论文 `_ 的第二节，能够利用梯度的一阶矩估计和二阶矩估计动态调整每个参数的学习率。 - -其参数更新的计算公式如下： - -.. math:: - \\t = t + 1 -.. math:: - moment\_1\_out=\beta_1∗moment\_1+(1−\beta_1)∗grad -.. math:: - moment\_2\_out=\beta_2∗moment\_2+(1−\beta_2)∗grad*grad -.. math:: - learning\_rate=learning\_rate*\frac{\sqrt{1-\beta_2^t}}{1-\beta_1^t} -.. math:: - param\_out=param-learning\_rate*\frac{moment\_1}{\sqrt{moment\_2}+\epsilon}\\ - -相关论文：`Adam: A Method for Stochastic Optimization `_ - -参数: - - **learning_rate** (float|Variable，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个值为浮点型的Variable，默认值为0.001 - - **parameter_list** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 - - **beta1** (float|Variable, 可选) - 一阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Variable类型。默认值为0.9 - - **beta2** (float|Variable, 可选) - 二阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Variable类型。默认值为0.999 - - **epsilon** (float, 可选) - 保持数值稳定性的短浮点类型值，默认值为1e-08 - - **regularization** (WeightDecayRegularizer，可选) - 正则化方法。支持两种正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 - :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； - 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 - - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 - 默认值为None，此时将不进行梯度裁剪。 - - **name** (str, 可选)- 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None - - **lazy_mode** （bool, 可选） - 设为True时，仅更新当前具有梯度的元素。官方Adam算法有两个移动平均累加器（moving-average accumulators）。累加器在每一步都会更新。在密集模式和稀疏模式下，两条移动平均线的每个元素都会更新。如果参数非常大，那么更新可能很慢。 lazy mode仅更新当前具有梯度的元素，所以它会更快。但是这种模式与原始的算法有不同的描述，可能会导致不同的结果，默认为False - - -**代码示例** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - - place = fluid.CPUPlace() - main = fluid.Program() - with fluid.program_guard(main): - x = fluid.layers.data(name='x', shape=[13], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_cost = fluid.layers.mean(cost) - adam_optimizer = fluid.optimizer.AdamOptimizer(0.01) - adam_optimizer.minimize(avg_cost) - - fetch_list = [avg_cost] - train_reader = paddle.batch( - paddle.dataset.uci_housing.train(), batch_size=1) - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - for data in train_reader(): - exe.run(main, feed=feeder.feed(data), fetch_list=fetch_list) - -.. code-block:: python - - # Adam with beta1/beta2 as Variable - import paddle - import paddle.fluid as fluid - import paddle.fluid.layers.learning_rate_scheduler as lr_scheduler - - place = fluid.CPUPlace() - main = fluid.Program() - with fluid.program_guard(main): - x = fluid.data(name='x', shape=[None, 13], dtype='float32') - y = fluid.data(name='y', shape=[None, 1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_cost = fluid.layers.mean(cost) - - # define beta decay variable - def get_decayed_betas(beta1_init, beta2_init, decay_steps, decay_rate): - global_step = lr_scheduler._decay_step_counter() - - beta1 = fluid.layers.create_global_var( - shape=[1], - value=float(beta1_init), - dtype='float32', - # set persistable for save checkpoints and resume - persistable=True, - name="beta1") - beta2 = fluid.layers.create_global_var( - shape=[1], - value=float(beta2_init), - dtype='float32', - # set persistable for save checkpoints and resume - persistable=True, - name="beta2") - - div_res = global_step / decay_steps - decayed_beta1 = beta1_init * (decay_rate**div_res) - decayed_beta2 = beta2_init * (decay_rate**div_res) - fluid.layers.assign(decayed_beta1, beta1) - fluid.layers.assign(decayed_beta2, beta2) - - return beta1, beta2 - - beta1, beta2 = get_decayed_betas(0.9, 0.99, 1e5, 0.9) - adam_optimizer = fluid.optimizer.AdamOptimizer( - learning_rate=0.01, - beta1=beta1, - beta2=beta2) - adam_optimizer.minimize(avg_cost) - - fetch_list = [avg_cost] - train_reader = paddle.batch( - paddle.dataset.uci_housing.train(), batch_size=1) - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - for data in train_reader(): - exe.run(main, feed=feeder.feed(data), fetch_list=fetch_list) - - -.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None) - -为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameter_list中的Parameters，最小化网络损失值loss。 - -参数： - - **loss** (Variable) – 需要最小化的损失值变量 - - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` - - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter - - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None - -返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 - -返回类型： tuple - -**代码示例** - -.. code-block:: python - - import numpy - import paddle.fluid as fluid - - x = fluid.layers.data(name='X', shape=[13], dtype='float32') - y = fluid.layers.data(name='Y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - loss = fluid.layers.mean(cost) - adam = fluid.optimizer.AdamOptimizer(learning_rate=0.2) - adam.minimize(loss) - - place = fluid.CPUPlace() # fluid.CUDAPlace(0) - exe = fluid.Executor(place) - - x = numpy.random.random(size=(10, 13)).astype('float32') - y = numpy.random.random(size=(10, 1)).astype('float32') - exe.run(fluid.default_startup_program()) - outs = exe.run(program=fluid.default_main_program(), - feed={'X': x, 'Y': y}, - fetch_list=[loss.name]) - - -.. py:method:: clear_gradients() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - - -清除需要优化的参数的梯度。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - with fluid.dygraph.guard(): - value = np.arange(26).reshape(2, 13).astype("float32") - a = fluid.dygraph.to_variable(value) - linear = fluid.Linear(13, 5, dtype="float32") - optimizer = fluid.optimizer.Adam(learning_rate=0.02, - parameter_list=linear.parameters()) - out = linear(a) - out.backward() - optimizer.minimize(out) - optimizer.clear_gradients() - -.. py:method:: set_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -手动设置当前 ``optimizer`` 的学习率。当使用LearningRateDecay时，无法使用该API手动设置学习率，因为这将导致冲突。 - -参数： - value (float|Variable) - 需要设置的学习率的值。 - -返回：无 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - linear = fluid.dygraph.nn.Linear(10, 10) - adam = fluid.optimizer.Adam(0.1, parameter_list=linear.parameters()) - # 通过Python float数值手动设置学习率 - lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] - for i in range(5): - adam.set_lr(lr_list[i]) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.2 - # current lr is 0.3 - # current lr is 0.4 - # current lr is 0.5 - # current lr is 0.6 - - - # 通过 框架的Variable 设置学习率 - lr_var = fluid.layers.create_global_var(shape=[1], value=0.7, dtype='float32') - adam.set_lr(lr_var) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.7 - - - -.. py:method:: current_step_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -获取当前步骤的学习率。当不使用LearningRateDecay时，每次调用的返回值都相同，否则返回当前步骤的学习率。 - -返回：当前步骤的学习率。 - -返回类型：float - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # example1: LearningRateDecay is not used, return value is all the same - with fluid.dygraph.guard(): - emb = fluid.dygraph.Embedding([10, 10]) - adam = fluid.optimizer.Adam(0.001, parameter_list = emb.parameters()) - lr = adam.current_step_lr() - print(lr) # 0.001 - - # example2: PiecewiseDecay is used, return the step learning rate - with fluid.dygraph.guard(): - inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") - linear = fluid.dygraph.nn.Linear(10, 10) - inp = fluid.dygraph.to_variable(inp) - out = linear(inp) - loss = fluid.layers.reduce_mean(out) - - bd = [2, 4, 6, 8] - value = [0.2, 0.4, 0.6, 0.8, 1.0] - adam = fluid.optimizer.Adam(fluid.dygraph.PiecewiseDecay(bd, value, 0), - parameter_list=linear.parameters()) - - # first step: learning rate is 0.2 - np.allclose(adam.current_step_lr(), 0.2, rtol=1e-06, atol=0.0) # True - - # learning rate for different steps - ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] - for i in range(12): - adam.minimize(loss) - lr = adam.current_step_lr() - np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True - diff --git a/doc/paddle/api/paddle/fluid/optimizer/Adam_cn.rst b/doc/paddle/api/paddle/fluid/optimizer/Adam_cn.rst deleted file mode 100644 index 2c8f8e567ab30678e7e346733c4f9b2928df4623..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/optimizer/Adam_cn.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _cn_api_fluid_optimizer_Adam: - -Adam -------------------------------- - -.. py:attribute:: paddle.fluid.optimizer.Adam - - - - -``AdamOptimizer`` 的别名 - - - - - diff --git a/doc/paddle/api/paddle/fluid/optimizer/AdamaxOptimizer_cn.rst b/doc/paddle/api/paddle/fluid/optimizer/AdamaxOptimizer_cn.rst deleted file mode 100644 index 1260ec166e3ac646520e7e20da85ff1712d96448..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/optimizer/AdamaxOptimizer_cn.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. _cn_api_fluid_optimizer_AdamaxOptimizer: - -AdamaxOptimizer -------------------------------- - -.. py:class:: paddle.fluid.optimizer.AdamaxOptimizer(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameter_list=None, regularization=None, grad_clip=None, name=None) - - - - -Adamax优化器是参考 `Adam论文 `_ 第7节Adamax优化相关内容所实现的。Adamax算法是基于无穷大范数的 `Adam `_ 算法的一个变种，使学习率更新的算法更加稳定和简单。 - -其参数更新的计算公式如下: - -.. math:: - \\t = t + 1 -.. math:: - moment\_out=\beta_1∗moment+(1−\beta_1)∗grad -.. math:: - inf\_norm\_out=\max{(\beta_2∗inf\_norm+\epsilon, \left|grad\right|)} -.. math:: - learning\_rate=\frac{learning\_rate}{1-\beta_1^t} -.. math:: - param\_out=param−learning\_rate*\frac{moment\_out}{inf\_norm\_out}\\ - -相关论文：`Adam: A Method for Stochastic Optimization `_ - -论文中没有 ``epsilon`` 参数。但是，为了保持数值稳定性， 避免除0错误， 此处增加了这个参数。 - -参数： - - **learning_rate** (float|Variable，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个值为浮点型的Variable，默认值为0.001 - - **beta1** (float, 可选) - 一阶矩估计的指数衰减率，默认值为0.9 - - **beta2** (float, 可选) - 二阶矩估计的指数衰减率，默认值为0.999 - - **epsilon** (float, 可选) - 保持数值稳定性的短浮点类型值，默认值为1e-08 - - **parameter_list** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 - - **regularization** (WeightDecayRegularizer，可选) - 正则化方法。支持两种正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 - :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； - 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 - - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 - 默认值为None，此时将不进行梯度裁剪。 - - **name** (str, 可选)- 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None - -.. note:: - 目前 ``AdamaxOptimizer`` 不支持 Sparse Parameter Optimization（稀疏参数优化）。 - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - import numpy - - # First create the Executor. - place = fluid.CPUPlace() # fluid.CUDAPlace(0) - exe = fluid.Executor(place) - - train_program = fluid.Program() - startup_program = fluid.Program() - with fluid.program_guard(train_program, startup_program): - data = fluid.layers.data(name='X', shape=[1], dtype='float32') - hidden = fluid.layers.fc(input=data, size=10) - loss = fluid.layers.mean(hidden) - adam = fluid.optimizer.AdamaxOptimizer(learning_rate=0.2) - adam.minimize(loss) - - # Run the startup program once and only once. - exe.run(startup_program) - - x = numpy.random.random(size=(10, 1)).astype('float32') - outs = exe.run(program=train_program, - feed={'X': x}, - fetch_list=[loss.name]) - -.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None) - -为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameter_list中的Parameters，最小化网络损失值loss。 - -参数： - - **loss** (Variable) – 需要最小化的损失值变量 - - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` - - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter - - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成集合，默认值为None - -返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 - -**代码示例**： - -.. code-block:: python - - import numpy - import paddle.fluid as fluid - - data = fluid.layers.data(name='X', shape=[1], dtype='float32') - hidden = fluid.layers.fc(input=data, size=10) - loss = fluid.layers.mean(hidden) - adam = fluid.optimizer.Adamax(learning_rate=0.2) - adam.minimize(loss) - - place = fluid.CPUPlace() # fluid.CUDAPlace(0) - exe = fluid.Executor(place) - - x = numpy.random.random(size=(10, 1)).astype('float32') - exe.run(fluid.default_startup_program()) - outs = exe.run(program=fluid.default_main_program(), - feed={'X': x}, - fetch_list=[loss.name]) - - - -.. py:method:: clear_gradients() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - - -清除需要优化的参数的梯度。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - with fluid.dygraph.guard(): - value = np.arange(26).reshape(2, 13).astype("float32") - a = fluid.dygraph.to_variable(value) - linear = fluid.Linear(13, 5, dtype="float32") - optimizer = fluid.optimizer.AdamaxOptimizer(learning_rate=0.2, - parameter_list=linear.parameters()) - out = linear(a) - out.backward() - optimizer.minimize(out) - optimizer.clear_gradients() - -.. py:method:: set_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -手动设置当前 ``optimizer`` 的学习率。当使用LearningRateDecay时，无法使用该API手动设置学习率，因为这将导致冲突。 - -参数： - value (float|Variable) - 需要设置的学习率的值。 - -返回：无 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - linear = fluid.dygraph.nn.Linear(10, 10) - adam = fluid.optimizer.Adam(0.1, parameter_list=linear.parameters()) - # 通过Python float数值手动设置学习率 - lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] - for i in range(5): - adam.set_lr(lr_list[i]) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.2 - # current lr is 0.3 - # current lr is 0.4 - # current lr is 0.5 - # current lr is 0.6 - - - # 通过 框架的Variable 设置学习率 - lr_var = fluid.layers.create_global_var(shape=[1], value=0.7, dtype='float32') - adam.set_lr(lr_var) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.7 - - - -.. py:method:: current_step_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -获取当前步骤的学习率。当不使用LearningRateDecay时，每次调用的返回值都相同，否则返回当前步骤的学习率。 - -返回：当前步骤的学习率。 - -返回类型：float - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # example1: LearningRateDecay is not used, return value is all the same - with fluid.dygraph.guard(): - emb = fluid.dygraph.Embedding([10, 10]) - adam = fluid.optimizer.Adam(0.001, parameter_list = emb.parameters()) - lr = adam.current_step_lr() - print(lr) # 0.001 - - # example2: PiecewiseDecay is used, return the step learning rate - with fluid.dygraph.guard(): - inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") - linear = fluid.dygraph.nn.Linear(10, 10) - inp = fluid.dygraph.to_variable(inp) - out = linear(inp) - loss = fluid.layers.reduce_mean(out) - - bd = [2, 4, 6, 8] - value = [0.2, 0.4, 0.6, 0.8, 1.0] - adam = fluid.optimizer.Adam(fluid.dygraph.PiecewiseDecay(bd, value, 0), - parameter_list=linear.parameters()) - - # first step: learning rate is 0.2 - np.allclose(adam.current_step_lr(), 0.2, rtol=1e-06, atol=0.0) # True - - # learning rate for different steps - ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] - for i in range(12): - adam.minimize(loss) - lr = adam.current_step_lr() - np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True - diff --git a/doc/paddle/api/paddle/fluid/optimizer/Adamax_cn.rst b/doc/paddle/api/paddle/fluid/optimizer/Adamax_cn.rst deleted file mode 100644 index 0413d5b109548833548752b8b9e22934633e5d42..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/optimizer/Adamax_cn.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _cn_api_fluid_optimizer_Adamax: - -Adamax -------------------------------- - -.. py:attribute:: paddle.fluid.optimizer.Adamax - - - - -``AdamaxOptimizer`` 的别名 - - - - - - diff --git a/doc/paddle/api/paddle/fluid/optimizer/RMSPropOptimizer_cn.rst b/doc/paddle/api/paddle/fluid/optimizer/RMSPropOptimizer_cn.rst deleted file mode 100644 index ac30efa78236c14772c6e5df08cec327e2abede1..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/optimizer/RMSPropOptimizer_cn.rst +++ /dev/null @@ -1,245 +0,0 @@ -.. _cn_api_fluid_optimizer_RMSPropOptimizer: - -RMSPropOptimizer -------------------------------- - -.. py:class:: paddle.fluid.optimizer.RMSPropOptimizer(learning_rate, rho=0.95, epsilon=1e-06, momentum=0.0, centered=False, parameter_list=None, regularization=None, grad_clip=None, name=None) - - - - -该接口实现均方根传播（RMSProp）法，是一种未发表的,自适应学习率的方法。原演示幻灯片中提出了RMSProp：[http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf]中的第29张。等式如下所示： - -.. math:: - r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ - w & = w - \frac{\eta} {\sqrt{r(w,t) + \epsilon}} \nabla Q_{i}(w) - -第一个等式计算每个权重平方梯度的移动平均值，然后将梯度除以 :math:`sqrtv（w，t）` 。 - -.. math:: - r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ - v(w, t) & = \beta v(w, t-1) +\frac{\eta} {\sqrt{r(w,t) +\epsilon}} \nabla Q_{i}(w)\\ - w & = w - v(w, t) - -如果居中为真： - -.. math:: - r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ - g(w, t) & = \rho g(w, t-1) + (1 -\rho)\nabla Q_{i}(w)\\ - v(w, t) & = \beta v(w, t-1) + \frac{\eta} {\sqrt{r(w,t) - (g(w, t))^2 +\epsilon}} \nabla Q_{i}(w)\\ - w & = w - v(w, t) - -其中， :math:`ρ` 是超参数，典型值为0.9,0.95等。 :math:`beta` 是动量术语。 :math:`epsilon` 是一个平滑项，用于避免除零，通常设置在1e-4到1e-8的范围内。 - -参数： - - **learning_rate** （float） - 全局学习率。 - - **parameter_list** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 - - **rho** （float，可选） - rho是等式中的 :math:`rho` ，默认值0.95。 - - **epsilon** （float，可选） - 等式中的epsilon是平滑项，避免被零除，默认值1e-6。 - - **momentum** （float，可选） - 方程中的β是动量项，默认值0.0。 - - **centered** （bool，可选） - 如果为True，则通过梯度的估计方差,对梯度进行归一化；如果False，则由未centered的第二个moment归一化。将此设置为True有助于模型训练，但会消耗额外计算和内存资源。默认为False。 - - **regularization** (WeightDecayRegularizer，可选) - 正则化方法。支持两种正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 - :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； - 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 - - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 - 默认值为None，此时将不进行梯度裁剪。 - - **name** (str, 可选) - 可选的名称前缀，一般无需设置，默认值为None。 - -抛出异常: - - ``ValueError`` -如果 ``learning_rate`` ， ``rho`` ， ``epsilon`` ， ``momentum`` 为None。 - -**示例代码** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - place = fluid.CPUPlace() - main = fluid.Program() - with fluid.program_guard(main): - x = fluid.layers.data(name='x', shape=[13], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_cost = fluid.layers.mean(cost) - - rms_optimizer = fluid.optimizer.RMSProp(learning_rate=0.1) - rms_optimizer.minimize(avg_cost) - - fetch_list = [avg_cost] - train_reader = paddle.batch( - paddle.dataset.uci_housing.train(), batch_size=1) - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - for data in train_reader(): - exe.run(main, feed=feeder.feed(data), fetch_list=fetch_list) - - - -.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None) - -为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameter_list中的Parameters，最小化网络损失值loss。 - -参数： - - **loss** (Variable) – 需要最小化的损失值变量 - - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` - - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter - - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None - -返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 - -返回类型： tuple - -**示例代码** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - place = fluid.CPUPlace() - main = fluid.Program() - with fluid.program_guard(main): - x = fluid.layers.data(name='x', shape=[13], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_cost = fluid.layers.mean(cost) - - rms_optimizer = fluid.optimizer.RMSProp(learning_rate=0.1) - rms_optimizer.minimize(avg_cost) - - fetch_list = [avg_cost] - train_reader = paddle.batch( - paddle.dataset.uci_housing.train(), batch_size=1) - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - for data in train_reader(): - exe.run(main, feed=feeder.feed(data), fetch_list=fetch_list) - - - -.. py:method:: clear_gradients() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - - -清除需要优化的参数的梯度。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - with fluid.dygraph.guard(): - value = np.arange(26).reshape(2, 13).astype("float32") - a = fluid.dygraph.to_variable(value) - linear = fluid.Linear(13, 5, dtype="float32") - optimizer = fluid.optimizer.RMSPropOptimizer(learning_rate=0.01, - parameter_list=linear.parameters()) - out = linear(a) - out.backward() - optimizer.minimize(out) - optimizer.clear_gradients() - -.. py:method:: set_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -手动设置当前 ``optimizer`` 的学习率。当使用LearningRateDecay时，无法使用该API手动设置学习率，因为这将导致冲突。 - -参数： - value (float|Variable) - 需要设置的学习率的值。 - -返回：无 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - linear = fluid.dygraph.nn.Linear(10, 10) - adam = fluid.optimizer.Adam(0.1, parameter_list=linear.parameters()) - # 通过Python float数值手动设置学习率 - lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] - for i in range(5): - adam.set_lr(lr_list[i]) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.2 - # current lr is 0.3 - # current lr is 0.4 - # current lr is 0.5 - # current lr is 0.6 - - - # 通过 框架的Variable 设置学习率 - lr_var = fluid.layers.create_global_var(shape=[1], value=0.7, dtype='float32') - adam.set_lr(lr_var) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.7 - - -.. py:method:: current_step_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -获取当前步骤的学习率。当不使用LearningRateDecay时，每次调用的返回值都相同，否则返回当前步骤的学习率。 - -返回：当前步骤的学习率。 - -返回类型：float - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # example1: LearningRateDecay is not used, return value is all the same - with fluid.dygraph.guard(): - emb = fluid.dygraph.Embedding([10, 10]) - adam = fluid.optimizer.Adam(0.001, parameter_list = emb.parameters()) - lr = adam.current_step_lr() - print(lr) # 0.001 - - # example2: PiecewiseDecay is used, return the step learning rate - with fluid.dygraph.guard(): - inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") - linear = fluid.dygraph.nn.Linear(10, 10) - inp = fluid.dygraph.to_variable(inp) - out = linear(inp) - loss = fluid.layers.reduce_mean(out) - - bd = [2, 4, 6, 8] - value = [0.2, 0.4, 0.6, 0.8, 1.0] - adam = fluid.optimizer.Adam(fluid.dygraph.PiecewiseDecay(bd, value, 0), - parameter_list=linear.parameters()) - - # first step: learning rate is 0.2 - np.allclose(adam.current_step_lr(), 0.2, rtol=1e-06, atol=0.0) # True - - # learning rate for different steps - ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] - for i in range(12): - adam.minimize(loss) - lr = adam.current_step_lr() - np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True - diff --git a/doc/paddle/api/paddle/optimizer/SGDOptimizer_cn.rst b/doc/paddle/api/paddle/fluid/optimizer/SGDOptimizer_cn.rst similarity index 100% rename from doc/paddle/api/paddle/optimizer/SGDOptimizer_cn.rst rename to doc/paddle/api/paddle/fluid/optimizer/SGDOptimizer_cn.rst diff --git a/doc/paddle/api/paddle/fluid/profiler_cn.rst b/doc/paddle/api/paddle/fluid/profiler_cn.rst deleted file mode 100644 index c3ae718c596611f11731ad4cef6b993f66bfaf62..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/profiler_cn.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. _cn_api_fluid_profiler_profiler: - -profiler -------------------------------- - -.. py:function:: paddle.fluid.profiler.profiler(state, sorted_key=None, profile_path='/tmp/profile', tracer_option='Default') - - - - -通用性能分析器 。与 :ref:`cn_api_fluid_profiler_cuda_profiler` 不同，此分析器可用于分析CPU和GPU程序。 - -参数: - - **state** (str) – 性能分析状态, 取值为 'CPU' 或 'GPU' 或 'All'。'CPU'表示只分析CPU上的性能；'GPU'表示同时分析CPU和GPU上的性能；'All'表示除了同时分析CPU和GPU上的性能外，还将生成 `性能分析的时间轴信息 <../../advanced_usage/development/profiling/timeline_cn.html>`_ 。 - - **sorted_key** (str，可选) – 性能分析结果的打印顺序，取值为None、'call'、'total'、'max'、'min'、'ave'之一。默认值为None，表示按照第一次结束时间顺序打印；'call'表示按调用的数量进行排序；'total'表示按总执行时间排序；'max'表示按最大执行时间排序；'min'表示按最小执行时间排序；'ave'表示按平均执行时间排序。 - - **profile_path** (str，可选) – 如果性能分析状态为'All', 将生成的时间轴信息写入profile_path，默认输出文件为 ``/tmp/profile`` 。 - - **tracer_option** (str，可选) – 性能分析选项取值为 'Default' 或 'OpDetail' 或 'AllOpDetail', 此选项用于设置性能分析层次并打印不同层次的性能分析结果， `Default` 选项打印不同Op类型的性能分析结果， `OpDetail` 则会打印不同OP类型更详细的性能分析结果，比如compute和data transform。 `AllOpDetail` 和 `OpDetail` 类似，但是打印的是不同Op名字的性能分析结果。 - -抛出异常： - - ``ValueError`` – 如果state取值不在 ['CPU', 'GPU', 'All']中，或sorted_key取值不在 [None, 'calls', 'total', 'max', 'min', 'ave']中，则抛出异常。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import paddle.fluid.profiler as profiler - import numpy as np - - epoc = 8 - dshape = [4, 3, 28, 28] - data = fluid.layers.data(name='data', shape=[3, 28, 28], dtype='float32') - conv = fluid.layers.conv2d(data, 20, 3, stride=[1, 1], padding=[1, 1]) - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - - with profiler.profiler('CPU', 'total', '/tmp/profile') as prof: - for i in range(epoc): - input = np.random.random(dshape).astype('float32') - exe.run(fluid.default_main_program(), feed={'data': input}) - -**结果示例** - -.. code-block:: text - - #### sorted_key = 'total', 'calls', 'max', 'min', 'ave' 结果 #### - # 示例结果中，除了Sorted by number of xxx in descending order in the same thread 这句随着sorted_key变化而不同，其余均相同。 - # 原因是，示例结果中，上述5列都已经按从大到小排列了。 - -------------------------> Profiling Report <------------------------- - - Place: CPU - Time unit: ms - Sorted by total time in descending order in the same thread - #Sorted by number of calls in descending order in the same thread - #Sorted by number of max in descending order in the same thread - #Sorted by number of min in descending order in the same thread - #Sorted by number of avg in descending order in the same thread - - Event Calls Total Min. Max. Ave. Ratio. - thread0::conv2d 8 129.406 0.304303 127.076 16.1758 0.983319 - thread0::elementwise_add 8 2.11865 0.193486 0.525592 0.264832 0.016099 - thread0::feed 8 0.076649 0.006834 0.024616 0.00958112 0.000582432 - - #### sorted_key = None 结果 #### - # 示例结果中，是按照Op结束时间顺序打印，因此打印顺序为feed->conv2d->elementwise_add - -------------------------> Profiling Report <------------------------- - - Place: CPU - Time unit: ms - Sorted by event first end time in descending order in the same thread - - Event Calls Total Min. Max. Ave. Ratio. - thread0::feed 8 0.077419 0.006608 0.023349 0.00967738 0.00775934 - thread0::conv2d 8 7.93456 0.291385 5.63342 0.99182 0.795243 - thread0::elementwise_add 8 1.96555 0.191884 0.518004 0.245693 0.196998 diff --git a/doc/paddle/api/paddle/fluid/regularizer/L1Decay_cn.rst b/doc/paddle/api/paddle/fluid/regularizer/L1Decay_cn.rst deleted file mode 100644 index d5b0dc6f548ce0708004df7adcf06522886fdc17..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/regularizer/L1Decay_cn.rst +++ /dev/null @@ -1,74 +0,0 @@ - -.. _cn_api_fluid_regularizer_L1Decay: - -L1Decay -------------------------------- - -.. py:attribute:: paddle.fluid.regularizer.L1Decay(regularization_coeff=0.0) - - - - -L1Decay实现L1权重衰减正则化，用于模型训练，使得权重矩阵稀疏。 - -该类生成的实例对象，需要设置在 :ref:`cn_api_fluid_ParamAttr` 或者 ``optimizer`` -(例如 :ref:`cn_api_fluid_optimizer_SGDOptimizer` )中，在 ``ParamAttr`` 中设置时， -只对该网络层中的参数生效；在 ``optimizer`` 中设置时，会对所有的参数生效；如果同时设置， -在 ``ParamAttr`` 中设置的优先级会高于在 ``optimizer`` 中设置。 - -具体实现中，L1权重衰减正则化的计算公式如下： - -.. math:: - \\L1WeightDecay=reg\_coeff∗sign(parameter)\\ - -参数： - - **regularization_coeff** (float) – L1正则化系数，默认值为0.0。 - -**代码示例1** - -.. code-block:: python - - import paddle.fluid as fluid - - main_prog = fluid.Program() - startup_prog = fluid.Program() - with fluid.program_guard(main_prog, startup_prog): - data = fluid.layers.data(name='image', shape=[3, 28, 28], dtype='float32') - label = fluid.layers.data(name='label', shape=[1], dtype='int64') - hidden = fluid.layers.fc(input=data, size=128, act='relu') - prediction = fluid.layers.fc(input=hidden, size=10, act='softmax') - loss = fluid.layers.cross_entropy(input=prediction, label=label) - avg_loss = fluid.layers.mean(loss) - optimizer = fluid.optimizer.Adagrad( - learning_rate=1e-4, - regularization=fluid.regularizer.L1Decay( - regularization_coeff=0.1)) - optimizer.minimize(avg_loss) - - -**代码示例2** - -.. code-block:: python - - # 在 ParamAttr 和 optimizer 中同时设置正则化 - import paddle.fluid as fluid - l1 = fluid.regularizer.L1Decay(regularization_coeff=0.1) - l2 = fluid.regularizer.L2Decay(regularization_coeff=0.1) - x = fluid.layers.uniform_random([3,4]) - - # 在ParamAttr中设置L1正则化 - w_param = fluid.ParamAttr(regularizer=l1) - hidden1 = fluid.layers.fc(x, 8, param_attr=w_param) # fc_0.w_0(L1), fc_0.b_0 - hidden2 = fluid.layers.fc(hidden1, 16, param_attr=w_param) # fc_1.w_0(L1), fc_1.b_0 - predict = fluid.layers.fc(hidden2, 32) # fc_3.w_0, fc_3.b_0 - avg_loss = fluid.layers.mean(predict) - - # 在optimizer中设置L2正则化 - optimizer = fluid.optimizer.SGD(learning_rate=1e-4, regularization=l2) - optimizer.minimize(avg_loss) - - # 将会打印出提示信息: - # Regularization of [fc_0.w_0, fc_1.w_0] have been set by ParamAttr or WeightNormParamAttr already. - # So, the Regularization of Optimizer will not take effect for these parameters! - - diff --git a/doc/paddle/api/paddle/fluid/regularizer/L2Decay_cn.rst b/doc/paddle/api/paddle/fluid/regularizer/L2Decay_cn.rst deleted file mode 100644 index d9c55c53f8c838965b7e5e588d9de4a2a6cce5d4..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/fluid/regularizer/L2Decay_cn.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _cn_api_fluid_regularizer_L2Decay: - -L2Decay -------------------------------- - -.. py:attribute:: paddle.fluid.regularizer.L2Decay - - - - -L2Decay实现L2权重衰减正则化，用于模型训练，有助于防止模型对训练数据过拟合。 - -该类生成的实例对象，需要设置在 :ref:`cn_api_fluid_ParamAttr` 或者 ``optimizer`` -(例如 :ref:`cn_api_fluid_optimizer_SGDOptimizer` )中，在 ``ParamAttr`` 中设置时， -只对该网络层中的参数生效；在 ``optimizer`` 中设置时，会对所有的参数生效；如果同时设置， -在 ``ParamAttr`` 中设置的优先级会高于在 ``optimizer`` 中设置。 - -具体实现中，L2权重衰减正则化的计算公式如下： - -.. math:: - \\L2WeightDecay=reg\_coeff*parameter\\ - -参数: - - **regularization_coeff** (float) – 正则化系数，默认值为0.0。 - -**代码示例1** - -.. code-block:: python - - import paddle.fluid as fluid - - main_prog = fluid.Program() - startup_prog = fluid.Program() - with fluid.program_guard(main_prog, startup_prog): - data = fluid.layers.data(name='image', shape=[3, 28, 28], dtype='float32') - label = fluid.layers.data(name='label', shape=[1], dtype='int64') - hidden = fluid.layers.fc(input=data, size=128, act='relu') - prediction = fluid.layers.fc(input=hidden, size=10, act='softmax') - loss = fluid.layers.cross_entropy(input=prediction, label=label) - avg_loss = fluid.layers.mean(loss) - optimizer = fluid.optimizer.Adagrad( - learning_rate=1e-4, - regularization=fluid.regularizer.L2Decay( - regularization_coeff=0.1)) - optimizer.minimize(avg_loss) - - -**代码示例2** - -.. code-block:: python - - # 在 ParamAttr 和 optimizer 中同时设置正则化 - import paddle.fluid as fluid - l1 = fluid.regularizer.L1Decay(regularization_coeff=0.1) - l2 = fluid.regularizer.L2Decay(regularization_coeff=0.1) - x = fluid.layers.uniform_random([3,4]) - - # 在ParamAttr中设置L1正则化 - w_param = fluid.ParamAttr(regularizer=l1) - hidden1 = fluid.layers.fc(x, 8, param_attr=w_param) # fc_0.w_0(L1), fc_0.b_0 - hidden2 = fluid.layers.fc(hidden1, 16, param_attr=w_param) # fc_1.w_0(L1), fc_1.b_0 - predict = fluid.layers.fc(hidden2, 32) # fc_3.w_0, fc_3.b_0 - avg_loss = fluid.layers.mean(predict) - - # 在optimizer中设置L2正则化 - optimizer = fluid.optimizer.SGD(learning_rate=1e-4, regularization=l2) - optimizer.minimize(avg_loss) - - # 将会打印出提示信息: - # Regularization of [fc_0.w_0, fc_1.w_0] have been set by ParamAttr or WeightNormParamAttr already. - # So, the Regularization of Optimizer will not take effect for these parameters! - diff --git a/doc/paddle/api/paddle/fluid/release_memory_cn.rst b/doc/paddle/api/paddle/fluid/release_memory_cn.rst index ef68a966501630d8a29aadee6622f2e16bfca447..724589bf79cd77f11c3ec9431019d31f08ffd74f 100644 --- a/doc/paddle/api/paddle/fluid/release_memory_cn.rst +++ b/doc/paddle/api/paddle/fluid/release_memory_cn.rst @@ -1,13 +1,13 @@ -.. _cn_api_fluid_release_memory: +.. _cn_api_fluid_transpiler_release_memory: release_memory ------------------------------- -.. py:function:: paddle.fluid.release_memory(input_program, skip_opt_set=None) +.. py:function:: paddle.fluid.transpiler.release_memory(input_program, skip_opt_set=None) :api_attr: 声明式编程模式（静态图) -**从1.6版本开始此接口不再推荐使用，请不要在新写的代码中使用它，1.6+版本已默认开启更优的存储优化策略** +**从1.6版本开始此接口不再推荐使用，请不要在新写的代码中使用它，1.6+版本已默认开启更优的存储优化策略** \ No newline at end of file diff --git a/doc/paddle/api/paddle/fluid/save_cn.rst b/doc/paddle/api/paddle/fluid/save_cn.rst index a15b23f2b5b1b798943dcb6d7ef49ce8fac229f1..f0276316bacd0d7b7cb7ef6df12b1f9ac08b759f 100644 --- a/doc/paddle/api/paddle/fluid/save_cn.rst +++ b/doc/paddle/api/paddle/fluid/save_cn.rst @@ -1,51 +1,80 @@ -.. _cn_api_fluid_save: +.. _cn_api_fluid_dygraph_jit_save: save -------------------------------- +----------------- +.. py:function:: paddle.fluid.dygraph.jit.save(layer, model_path, input_spec=None, configs=None) -.. py:function:: paddle.fluid.save(program, model_path) +将输入的经过 ``@declarative`` 装饰的 :ref:`cn_api_fluid_dygraph_Layer` 存储为 :ref:`cn_api_fluid_dygraph_TranslatedLayer` 格式的模型， +载入后可用于预测推理或者fine-tune训练。 -:api_attr: 声明式编程模式（静态图) -:alias_main: paddle.save -:alias: paddle.save,paddle.tensor.save,paddle.tensor.io.save -:old_api: paddle.fluid.save +该接口将会将输入 :ref:`cn_api_fluid_dygraph_Layer` 转写后的模型结构 ``Program`` 和所有必要的持久参数变量存储至输入路径 ``model_path`` 中。 +默认存储的 ``Program`` 文件名为 ``__model__``， 默认存储持久参数变量的文件名为 ``__variables__``， +同时会将变量的一些描述信息存储至文件 ``__variables.info__``，这些额外的信息将在fine-tune训练中使用。 +存储的模型能够被以下API载入使用： + - :ref:`cn_api_fluid_dygraph_jit_load` + - :ref:`cn_api_fluid_io_load_inference_model` （需要配置参数 ``params_filename='__variables__'`` ） + - 其他预测库API -该接口将传入的参数、优化器信息和网络描述保存到 ``model_path`` 。 +参数： + - **layer** (Layer) - 需要存储的 :ref:`cn_api_fluid_dygraph_Layer` 对象。输入的 ``Layer`` 需要经过 ``@declarative`` 装饰。 + - **model_path** (str) - 存储模型的目录。 + - **input_spec** (list[Variable], 可选) - 描述存储模型的输入。此参数是传入当前存储的 ``TranslatedLayer`` forward方法的一个示例输入。如果为 ``None`` ，所有原 ``Layer`` forward方法的输入变量将都会被配置为存储模型的输入变量。默认为 ``None``。 + - **configs** (SaveLoadConfig, 可选) - 用于指定额外配置选项的 :ref:`cn_api_fluid_dygraph_jit_SaveLoadConfig` 对象。默认为 ``None``。 -参数包含所有的可训练 :ref:`cn_api_fluid_Variable` ，将保存到后缀为 ``.pdparams`` 的文件中。 +返回：无 -优化器信息包含优化器使用的所有变量。对于Adam优化器，包含beta1、beta2、momentum等。 -所有信息将保存到后缀为 ``.pdopt`` 的文件中。（如果优化器没有需要保存的变量（如sgd），则不会生成）。 - -网络描述是程序的描述。它只用于部署。描述将保存到后缀为 ``.pdmodel`` 的文件中。 - -参数: - - **program** ( :ref:`cn_api_fluid_Program` ) – 要保存的Program。 - - **model_path** (str) – 保存program的文件前缀。格式为 ``目录名称/文件前缀``。如果文件前缀为空字符串，会引发异常。 - -返回: 无 - -**代码示例** +**示例代码** .. code-block:: python + import numpy as np import paddle.fluid as fluid - - x = fluid.data(name="x", shape=[10, 10], dtype='float32') - y = fluid.layers.fc(x, 10) - z = fluid.layers.fc(y, 10) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - - fluid.save(fluid.default_main_program(), "./test_path") - - - - - - - + from paddle.fluid.dygraph import Linear + from paddle.fluid.dygraph import declarative + BATCH_SIZE = 32 + BATCH_NUM = 20 + def random_batch_reader(): + def _get_random_images_and_labels(image_shape, label_shape): + image = np.random.random(size=image_shape).astype('float32') + label = np.random.random(size=label_shape).astype('int64') + return image, label + def __reader__(): + for _ in range(BATCH_NUM): + batch_image, batch_label = _get_random_images_and_labels( + [BATCH_SIZE, 784], [BATCH_SIZE, 1]) + yield batch_image, batch_label + return __reader__ + class LinearNet(fluid.dygraph.Layer): + def __init__(self, in_size, out_size): + super(LinearNet, self).__init__() + self._linear = Linear(in_size, out_size) + @declarative + def forward(self, x): + return self._linear(x) + # 开启命令式编程模式 + fluid.enable_dygraph() + # 创建网络 + net = LinearNet(784, 1) + adam = fluid.optimizer.AdamOptimizer(learning_rate=0.1, parameter_list=net.parameters()) + # 创建DataLoader + train_loader = fluid.io.DataLoader.from_generator(capacity=5) + train_loader.set_batch_generator(random_batch_reader()) + # 训练 + for data in train_loader(): + img, label = data + label.stop_gradient = True + cost = net(img) + loss = fluid.layers.cross_entropy(cost, label) + avg_loss = fluid.layers.mean(loss) + avg_loss.backward() + adam.minimize(avg_loss) + net.clear_gradients() + # 存储模型 + model_path = "linear.example.model" + fluid.dygraph.jit.save( + layer=net, + model_path=model_path, + input_spec=[img]) diff --git a/doc/paddle/api/paddle/fluid/unique_name/guard_cn.rst b/doc/paddle/api/paddle/fluid/unique_name/guard_cn.rst index 651e8b6b5998545b5b8cf6553bc39c5b59495c25..7c457eb15118baf6823be9e404fc2fa053b6a2f6 100644 --- a/doc/paddle/api/paddle/fluid/unique_name/guard_cn.rst +++ b/doc/paddle/api/paddle/fluid/unique_name/guard_cn.rst @@ -1,35 +1,35 @@ -.. _cn_api_fluid_dygraph_guard: +.. _cn_api_fluid_unique_name_guard: guard ------------------------------- +.. py:function:: paddle.fluid.unique_name.guard(new_generator=None) -.. py:function:: paddle.fluid.dygraph.guard(place=None) -:api_attr: 命令式编程模式（动态图) +该接口用于更改命名空间，与with语句一起使用。使用后，在with语句的上下文中使用新的命名空间，调用generate接口时相同前缀的名称将从0开始重新编号。 -通过with语句创建一个dygraph运行的context，执行context代码。 +参数: + - **new_generator** (str|bytes, 可选) - 新命名空间的名称。请注意，Python2中的str在Python3中被区分为str和bytes两种，因此这里有两种类型。 缺省值为None，若不为None，new_generator将作为前缀添加到generate接口产生的唯一名称中。 -参数： - - **place** (fluid.CPUPlace|fluid.CUDAPlace, 可选) – 动态图执行的设备，可以选择cpu，gpu，如果用户未制定，则根据用户paddle编译的方式来选择运行的设备，如果编译的cpu版本，则在cpu上运行，如果是编译的gpu版本，则在gpu上运行。默认值：None。 - -返回： None +返回: 无。 **代码示例** .. code-block:: python - import numpy as np - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - inp = np.ones([3, 1024], dtype='float32') - t = fluid.dygraph.base.to_variable(inp) - linear1 = fluid.Linear(1024, 4, bias_attr=False) - linear2 = fluid.Linear(4, 4) - ret = linear1(t) - dy_ret = linear2(ret) + import paddle.fluid as fluid + with fluid.unique_name.guard(): + name_1 = fluid.unique_name.generate('fc') + with fluid.unique_name.guard(): + name_2 = fluid.unique_name.generate('fc') + print(name_1, name_2) # fc_0, fc_0 + + with fluid.unique_name.guard('A'): + name_1 = fluid.unique_name.generate('fc') + with fluid.unique_name.guard('B'): + name_2 = fluid.unique_name.generate('fc') + print(name_1, name_2) # Afc_0, Bfc_0 diff --git a/doc/paddle/api/paddle/framework/BackwardStrategy_cn.rst b/doc/paddle/api/paddle/framework/BackwardStrategy_cn.rst deleted file mode 100644 index e5bee2a137388d489c2a8de4e31ff6e4ace4b006..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/framework/BackwardStrategy_cn.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _cn_api_fluid_dygraph_BackwardStrategy: - -BackwardStrategy -------------------------------- - - -.. py:class:: paddle.fluid.dygraph.BackwardStrategy - -:api_attr: 命令式编程模式（动态图) - - - -**注意：该API只在动态图下生效** - -BackwardStrategy是描述动态图反向执行的策略，主要功能是定义动态图反向执行时的不同策略 - -**属性：** - -.. py:attribute:: sort_sum_gradient - -是否按照前向执行的逆序加和多个梯度，例如当 x_var（ :ref:`api_guide_Variable` ）作为多个OP（这里以 :ref:`cn_api_fluid_layers_scale` 为例）的输入时，其产生的梯度是否按照前向书写时的 -逆序加和，默认为False - - -**代码示例** - -.. code-block:: python - - import numpy as np - import paddle.fluid as fluid - - x = np.ones([2, 2], np.float32) - with fluid.dygraph.guard(): - x_var = fluid.dygraph.to_variable(x) - sums_inputs = [] - # 这里x_var将作为多个输入scale的输入 - for _ in range(10): - sums_inputs.append(fluid.layers.scale(x_var)) - ret2 = fluid.layers.sums(sums_inputs) - loss2 = fluid.layers.reduce_sum(ret2) - backward_strategy = fluid.dygraph.BackwardStrategy() - backward_strategy.sort_sum_gradient = True - loss2.backward(backward_strategy) - - - - - - diff --git a/doc/paddle/api/paddle/jit/SaveLoadConfig_cn.rst b/doc/paddle/api/paddle/framework/SaveLoadConfig_cn.rst similarity index 89% rename from doc/paddle/api/paddle/jit/SaveLoadConfig_cn.rst rename to doc/paddle/api/paddle/framework/SaveLoadConfig_cn.rst index ddbbd84d6b67c0a7466f4572cc72c354d9921c58..cbee1bab234be6f53f83061c52139093513d321b 100644 --- a/doc/paddle/api/paddle/jit/SaveLoadConfig_cn.rst +++ b/doc/paddle/api/paddle/framework/SaveLoadConfig_cn.rst @@ -1,9 +1,9 @@ .. _cn_api_fluid_dygraph_jit_SaveLoadConfig: SaveLoadConfig --------------- +------------------------------- -.. py:class:: paddle.SaveLoadConfig() +.. py:class:: paddle.fluid.dygraph.jit.SaveLoadConfig() 用于配置接口 :ref:`cn_api_fluid_dygraph_jit_save` 和 :ref:`cn_api_fluid_dygraph_jit_load` 存储载入 :ref:`cn_api_fluid_dygraph_TranslatedLayer` 时的附加选项。 @@ -271,38 +271,3 @@ SaveLoadConfig infer_net = fluid.dygraph.jit.load(model_path, configs=configs) x = fluid.dygraph.to_variable(np.random.random((4, 8)).astype('float32')) pred = infer_net(x) - - -.. py:attribute:: keep_name_table - -配置是否保留 ``paddle.load`` 载入结果中 ``structured_name`` 到真实的参数变量名的映射表。这个映射表是调用 ``paddle.save`` 时存储的，一般仅用于调试，移除此映射表不影响真实的训练和预测。默认情况下不会保留在 ``paddle.load`` 的结果中。默认值为False。 - -.. note:: - 该配置仅用于 ``paddle.load`` 方法。 - -**示例代码** - .. code-block:: python - - import paddle - - paddle.disable_static() - - linear = paddle.nn.Linear(5, 1) - - state_dict = linear.state_dict() - paddle.save(state_dict, "paddle_dy") - - configs = paddle.SaveLoadConfig() - configs.keep_name_table = True - para_state_dict, _ = paddle.load("paddle_dy", configs) - - print(para_state_dict) - # the name_table is 'StructuredToParameterName@@' - # {'bias': array([0.], dtype=float32), - # 'StructuredToParameterName@@': - # {'bias': u'linear_0.b_0', 'weight': u'linear_0.w_0'}, - # 'weight': array([[ 0.04230034], - # [-0.1222527 ], - # [ 0.7392676 ], - # [-0.8136974 ], - # [ 0.01211023]], dtype=float32)} diff --git a/doc/paddle/api/paddle/hapi/Model_cn.rst b/doc/paddle/api/paddle/hapi/Model_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..4e147a58a436901c93e9363cf48e62ecc434a4b7 --- /dev/null +++ b/doc/paddle/api/paddle/hapi/Model_cn.rst @@ -0,0 +1,530 @@ +.. _cn_api_paddle_incubate_hapi_model_Model: + +Model +------------------------------- + +.. py:class:: paddle.incubate.hapi.model.Model() + + ``Model`` 对象是一个具备训练、测试、推理的神经网络。该对象同时支持静态图和动态图模式，通过 ``fluid.enable_dygraph()`` 来切换。需要注意的是，该开关需要在实例化 ``Model`` 对象之前使用。 在静态图模式下，输入需要使用 ``hapi.Input`` 来定义。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + import paddle.fluid as fluid + + from paddle.incubate.hapi.model import Model, Input, set_device + from paddle.incubate.hapi.loss import CrossEntropy + from paddle.incubate.hapi.datasets import MNIST + from paddle.incubate.hapi.metrics import Accuracy + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(784, 10, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + device = set_device('cpu') + + # 切换成动态图模式，默认使用静态图模式 + fluid.enable_dygraph(device) + + model = MyModel() + optim = fluid.optimizer.SGD(learning_rate=1e-3, + parameter_list=model.parameters()) + + inputs = [Input([None, 784], 'float32', name='x')] + labels = [Input([None, 1], 'int64', name='label')] + + mnist_data = MNIST(mode='train', chw_format=False) + model.prepare(optim, + CrossEntropy(average=True), + Accuracy(), + inputs, + labels, + device=device) + model.fit(mnist_data, epochs=2, batch_size=32, verbose=1) + + +.. py:function:: train_batch(inputs, labels=None) + +在一个批次的数据上进行训练。 + +参数： + - **inputs** (list) - 1维列表，每个元素都是一批次的输入数据，数据类型为 ``numpy.ndarray``。 + - **labels** (list) - 1维列表，每个元素都是一批次的输入标签，数据类型为 ``numpy.ndarray`` 。默认值：None。 + +返回：一个列表，包含了训练损失函数的值，如果定义了评估函数，还会包含评估函数得到的指标。 + +返回类型：list + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle.fluid as fluid + + from paddle.fluid.dygraph import Linear + from paddle.incubate.hapi.loss import CrossEntropy + from paddle.incubate.hapi.model import Model, Input, set_device + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = Linear(784, 10, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + device = set_device('cpu') + fluid.enable_dygraph(device) + + model = MyModel() + optim = fluid.optimizer.SGD(learning_rate=1e-3, + parameter_list=model.parameters()) + + inputs = [Input([None, 784], 'float32', name='x')] + labels = [Input([None, 1], 'int64', name='label')] + model.prepare(optim, + CrossEntropy(average=True), + inputs=inputs, + labels=labels, + device=device) + data = np.random.random(size=(4,784)).astype(np.float32) + label = np.random.randint(0, 10, size=(4, 1)).astype(np.int64) + loss = model.train_batch([data], [label]) + print(loss) + +.. py:function:: eval_batch(inputs, labels=None) + +在一个批次的数据上进行评估。 + +参数： + - **inputs** (list) - 1维列表，每个元素都是一批次的输入数据，数据类型为 ``numpy.ndarray`` 。 + - **labels** (list) - 1维列表，每个元素都是一批次的输入标签，数据类型为 ``numpy.ndarray`` 。默认值：None。 + +返回：一个列表，包含了评估损失函数的值，如果定义了评估函数，还会包含评估函数得到的指标。 + +返回类型：list + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle.fluid as fluid + + from paddle.incubate.hapi.loss import CrossEntropy + from paddle.incubate.hapi.model import Model, Input, set_device + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(784, 10, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + device = set_device('cpu') + fluid.enable_dygraph(device) + + model = MyModel() + optim = fluid.optimizer.SGD(learning_rate=1e-3, + parameter_list=model.parameters()) + + inputs = [Input([None, 784], 'float32', name='x')] + labels = [Input([None, 1], 'int64', name='label')] + model.prepare(optim, + CrossEntropy(average=True), + inputs=inputs, + labels=labels, + device=device) + data = np.random.random(size=(4,784)).astype(np.float32) + label = np.random.randint(0, 10, size=(4, 1)).astype(np.int64) + loss = model.eval_batch([data], [label]) + print(loss) + +.. py:function:: test_batch(inputs) + +在一个批次的数据上进行测试。 + +参数： + - **inputs** (list) - 1维列表，每个元素都是一批次的输入数据，数据类型为 ``numpy.ndarray`` 。 + +返回：一个列表，包含了模型的输出。 + +返回类型：list + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle.fluid as fluid + from paddle.incubate.hapi.model import Model, Input, set_device + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(784, 1, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + device = set_device('cpu') + fluid.enable_dygraph(device) + + model = MyModel() + inputs = [Input([None, 784], 'float32', name='x')] + model.prepare(inputs=inputs, + device=device) + data = np.random.random(size=(4,784)).astype(np.float32) + out = model.eval_batch([data]) + print(out) + +.. py:function:: save(path): + +将模型的参数和训练过程中优化器的信息保存到指定的路径。所有的模型参数都会保存到一个后缀为 ``.pdparams`` 的文件中。 +所有的优化器信息和相关参数，比如 ``Adam`` 优化器中的 ``beta1`` ， ``beta2`` ，``momentum`` 等，都会被保存到后缀为 ``.pdopt`` +的文件中。 + +参数： + - **path** (str) - 保存的文件名前缀。格式如 ``dirname/file_prefix`` 或者 ``file_prefix`` 。 + +返回：None + +**代码示例**： + +.. code-block:: python + + import paddle.fluid as fluid + from paddle.incubate.hapi.model import Model, set_device + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(784, 1, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + device = set_device('cpu') + fluid.enable_dygraph(device) + model = MyModel() + model.save('checkpoint/test') + +.. py:function:: load(path, skip_mismatch=False, reset_optimizer=False): + +从指定的文件中载入模型参数和优化器参数，如果不想恢复优化器参数信息，优化器信息文件可以不存在。 + +参数： + - **path** (str) - 保存参数或优化器信息的文件前缀。格式如 ``path.pdparams`` 或者 ``path.pdopt`` ，后者是非必要的，如果不想恢复优化器信息。 + - **skip_mismatch** (bool) - 是否需要跳过保存的模型文件中形状或名称不匹配的参数，设置为 ``False`` 时，当遇到不匹配的参数会抛出一个错误。默认值：False。 + - **reset_optimizer** (bool) - 设置为 ``True`` 时，会忽略提供的优化器信息文件。否则会载入提供的优化器信息。默认值：False。 + +返回：None + +**代码示例**： + +.. code-block:: python + + import paddle.fluid as fluid + from paddle.incubate.hapi.model import Model, set_device + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(784, 1, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + device = set_device('cpu') + fluid.enable_dygraph(device) + model = MyModel() + model.load('checkpoint/test') + +.. py:function:: parameters(*args, **kwargs): + +返回一个包含模型所有参数的列表。 + +返回：在静态图中返回一个包含 ``Parameter`` 的列表，在动态图中返回一个包含 ``ParamBase`` 的列表。 + +**代码示例**： + +.. code-block:: python + import paddle.fluid as fluid + + from paddle.incubate.hapi.model import Model, Input, set_device + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(20, 10, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + fluid.enable_dygraph() + model = MyModel() + params = model.parameters() + + +.. py:function:: prepare(optimizer=None, loss_function=None, metrics=None, inputs=None, labels=None, device=None): + +返回一个包含模型所有参数的列表。 + +参数： + - **optimizer** (Optimizer) - 当训练模型的，该参数必须被设定。当评估或测试的时候，该参数可以不设定。默认值：None。 + - **loss_function** (Loss) - 当训练模型的，该参数必须被设定。默认值：None。 + - **metrics** (Metric|list[Metric]) - 当该参数被设定时，所有给定的评估方法会在训练和测试时被运行，并返回对应的指标。默认值：None。 + - **inputs** (Input|list[Input]|dict) - 网络的输入，对于静态图，该参数必须给定。默认值：None。 + - **labels** (Input|list[Input]|dict) - 标签，网络的输入。对于静态图，在训练和评估时该参数必须给定。默认值：None。 + - **device** (str|fluid.CUDAPlace|fluid.CPUPlace|None) - 网络运行的设备，当不指定时，会根据环境和安装的 ``paddle`` 自动选择。默认值：None。 + +返回：None + +.. py:function:: fit(train_data=None, eval_data=None, batch_size=1, epochs=1, eval_freq=1, log_freq=10, save_dir=None, save_freq=1, verbose=2, drop_last=False, shuffle=True, num_workers=0, callbacks=None): + +训练模型。当 ``eval_data`` 给定时，会在 ``eval_freq`` 个 ``epoch`` 后进行一次评估。 + +参数： + - **train_data** (Dataset|DataLoader) - 一个可迭代的数据源，推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。默认值：None。 + - **eval_data** (Dataset|DataLoader) - 一个可迭代的数据源，推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。当给定时，会在每个 ``epoch`` 后都会进行评估。默认值：None。 + - **batch_size** (int) - 训练数据或评估数据的批大小，当 ``train_data`` 或 ``eval_data`` 为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：1。 + - **epochs** (int) - 训练的轮数。默认值：1。 + - **eval_freq** (int) - 评估的频率，多少个 ``epoch`` 评估一次。默认值：1。 + - **log_freq** (int) - 日志打印的频率，多少个 ``step`` 打印一次日志。默认值：1。 + - **save_dir** (str|None) - 保存模型的文件夹，如果不设定，将不保存模型。默认值：None。 + - **save_freq** (int) - 保存模型的频率，多少个 ``epoch`` 保存一次模型。默认值：1。 + - **verbose** (int) - 可视化的模型，必须为0，1，2。当设定为0时，不打印日志，设定为1时，使用进度条的方式打印日志，设定为2时，一行一行地打印日志。默认值：2。 + - **drop_last** (bool) - 是否丢弃训练数据中最后几个不足设定的批次大小的数据。默认值：False。 + - **shuffle** (bool) - 是否对训练数据进行洗牌。当 ``train_data`` 为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：True。 + - **num_workers** (int) - 启动子进程用于读取数据的数量。当 ``train_data`` 和 ``eval_data`` 都为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：True。 + - **callbacks** (Callback|list[Callback]|None) - ``Callback`` 的一个实例或实例列表。该参数不给定时，默认会插入 ``ProgBarLogger`` 和 ``ModelCheckpoint`` 这两个实例。默认值：None。 + +返回：None + +**代码示例**： + +.. code-block:: python + + # 1. 使用Dataset训练，并设置batch_size的例子。 + import paddle.fluid as fluid + + from paddle.incubate.hapi.model import Model, Input, set_device + from paddle.incubate.hapi.loss import CrossEntropy + from paddle.incubate.hapi.metrics import Accuracy + from paddle.incubate.hapi.datasets import MNIST + from paddle.incubate.hapi.vision.models import LeNet + + dynamic = True + device = set_device('cpu') + fluid.enable_dygraph(device) if dynamic else None + + train_dataset = MNIST(mode='train') + val_dataset = MNIST(mode='test') + + inputs = [Input([None, 1, 28, 28], 'float32', name='image')] + labels = [Input([None, 1], 'int64', name='label')] + + model = LeNet() + optim = fluid.optimizer.Adam( + learning_rate=0.001, parameter_list=model.parameters()) + model.prepare( + optim, + CrossEntropy(), + Accuracy(topk=(1, 2)), + inputs=inputs, + labels=labels, + device=device) + model.fit(train_dataset, + val_dataset, + epochs=2, + batch_size=64, + save_dir='mnist_checkpoint') + + # 2. 使用Dataloader训练的例子. + + from paddle.incubate.hapi.model import Model, Input, set_device + from paddle.incubate.hapi.loss import CrossEntropy + from paddle.incubate.hapi.metrics import Accuracy + from paddle.incubate.hapi.datasets import MNIST + from paddle.incubate.hapi.vision.models import LeNet + + dynamic = True + device = set_device('cpu') + fluid.enable_dygraph(device) if dynamic else None + + train_dataset = MNIST(mode='train') + train_loader = fluid.io.DataLoader(train_dataset, + places=device, batch_size=64) + val_dataset = MNIST(mode='test') + val_loader = fluid.io.DataLoader(val_dataset, + places=device, batch_size=64) + + inputs = [Input([None, 1, 28, 28], 'float32', name='image')] + labels = [Input([None, 1], 'int64', name='label')] + + model = LeNet() + optim = fluid.optimizer.Adam( + learning_rate=0.001, parameter_list=model.parameters()) + model.prepare( + optim, + CrossEntropy(), + Accuracy(topk=(1, 2)), + inputs=inputs, + labels=labels, + device=device) + model.fit(train_loader, + val_loader, + epochs=2, + save_dir='mnist_checkpoint') + + +.. py:function:: evaluate(eval_data, batch_size=1, log_freq=10, verbose=2, num_workers=0, callbacks=None): + +评估模型。 + +参数： + - **eval_data** (Dataset|DataLoader) - 一个可迭代的数据源，推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。默认值：None。 + - **batch_size** (int) - 训练数据或评估数据的批大小，当 ``eval_data`` 为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：1。 + - **log_freq** (int) - 日志打印的频率，多少个 ``step`` 打印一次日志。默认值：1。 + - **verbose** (int) - 可视化的模型，必须为0，1，2。当设定为0时，不打印日志，设定为1时，使用进度条的方式打印日志，设定为2时，一行一行地打印日志。默认值：2。 + - **num_workers** (int) - 启动子进程用于读取数据的数量。当 ``eval_data`` 为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：True。 + - **callbacks** (Callback|list[Callback]|None) - ``Callback`` 的一个实例或实例列表。该参数不给定时，默认会插入 ``ProgBarLogger`` 和 ``ModelCheckpoint`` 这两个实例。默认值：None。 + +返回：None + +**代码示例**： + +.. code-block:: python + + # declarative mode + import numpy as np + from paddle.incubate.hapi.metrics import Accuracy + from paddle.incubate.hapi.datasets import MNIST + from paddle.incubate.hapi.vision.transforms import Compose,Resize + from paddle.incubate.hapi.vision.models import LeNet + from paddle.incubate.hapi.model import Input, set_device + + + inputs = [Input([-1, 1, 28, 28], 'float32', name='image')] + labels = [Input([None, 1], 'int64', name='label')] + + val_dataset = MNIST(mode='test') + + model = LeNet() + model.prepare(metrics=Accuracy(), inputs=inputs, labels=labels) + + result = model.evaluate(val_dataset, batch_size=64) + print(result) + + # imperative mode + import paddle.fluid.dygraph as dg + place = set_device('cpu') + with dg.guard(place) as g: + model = LeNet() + model.prepare(metrics=Accuracy(), inputs=inputs, labels=labels) + + result = model.evaluate(val_dataset, batch_size=64) + print(result) + + +.. py:function:: predict(test_data, batch_size=1, num_workers=0, stack_outputs=False, callbacks=None): + +模型预测。 + +参数： + - **test_data** (Dataset|DataLoader) - 一个可迭代的数据源，推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。默认值：None。 + - **batch_size** (int) - 训练数据或评估数据的批大小，当 ``eval_data`` 为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：1。 + - **num_workers** (int) - 启动子进程用于读取数据的数量。当 ``eval_data`` 为 ``DataLoader`` 的实例时，该参数会被忽略。默认值：True。 + - **stack_outputs** (bool) - 是否将输出进行堆叠。默认值：False。 + - **callbacks** (Callback|list[Callback]|None) - ``Callback`` 的一个实例或实例列表。默认值：None。 + +返回：None + +**代码示例**： + +.. code-block:: python + + # declarative mode + import numpy as np + from paddle.incubate.hapi.metrics import Accuracy + from paddle.incubate.hapi.datasets import MNIST + from paddle.incubate.hapi.vision.transforms import Compose,Resize + from paddle.incubate.hapi.vision.models import LeNet + from paddle.incubate.hapi.model import Input, set_device + + class MnistDataset(MNIST): + def __init__(self, mode, return_label=True): + super(MnistDataset, self).__init__(mode=mode) + self.return_label = return_label + + def __getitem__(self, idx): + img = np.reshape(self.images[idx], [1, 28, 28]) + if self.return_label: + return img, np.array(self.labels[idx]).astype('int64') + return img, + + def __len__(self): + return len(self.images) + + inputs = [Input([-1, 1, 28, 28], 'float32', name='image')] + + test_dataset = MnistDataset(mode='test', return_label=False) + + model = LeNet() + model.prepare(inputs=inputs) + + result = model.predict(test_dataset, batch_size=64) + print(result) + + # imperative mode + import paddle.fluid.dygraph as dg + place = set_device('cpu') + with dg.guard(place) as g: + model = LeNet() + model.prepare(inputs=inputs) + + result = model.predict(test_dataset, batch_size=64) + print(result) + + +.. py:function:: save_inference_model(save_dir, model_filename=None, params_filename=None, model_only=False): + +模型预测。 + +参数： + - **save_dir** (str) - 保存推理模型的路径。 + - **model_filename** (str，可选) - 保存预测模型结构 ``Inference Program`` 的文件名称。若设置为None，则使用 ``__model__`` 作为默认的文件名。默认值：None。 + - **params_filename** (str，可选) - 保存预测模型所有相关参数的文件名称。若设置为None，则模型参数被保存在单独的文件中。 + - **model_only** (bool，可选) - 若为True，则只保存预测模型的网络结构，而不保存预测模型的网络参数。默认值：False。 + +返回：None + +**代码示例**： + +.. code-block:: python + + import paddle.fluid as fluid + + from paddle.incubate.hapi.model import Model, Input + + class MyModel(Model): + def __init__(self): + super(MyModel, self).__init__() + self._fc = fluid.dygraph.Linear(784, 1, act='softmax') + def forward(self, x): + y = self._fc(x) + return y + + model = MyModel() + inputs = [Input([-1, 1, 784], 'float32', name='input')] + model.prepare(inputs=inputs) + + model.save_inference_model('checkpoint/test') \ No newline at end of file diff --git a/doc/paddle/api/paddle/io/BatchSampler_cn.rst b/doc/paddle/api/paddle/io/BatchSampler_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d97e1af250b27c1b08959581b1a3981979a38d32 --- /dev/null +++ b/doc/paddle/api/paddle/io/BatchSampler_cn.rst @@ -0,0 +1,7 @@ +.. _cn_api_io_cn_BatchSampler: + +BatchSampler +------------------------------- +:doc_source: paddle.fluid.dataloader.BatchSampler + + diff --git a/doc/paddle/api/paddle/io/Dataset_cn.rst b/doc/paddle/api/paddle/io/Dataset_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..9cc4bf215405232188e577ad074d784ef2c06424 --- /dev/null +++ b/doc/paddle/api/paddle/io/Dataset_cn.rst @@ -0,0 +1,7 @@ +.. _cn_api_io_cn_Dataset: + +Dataset +------------------------------- +:doc_source: paddle.fluid.dataloader.Dataset + + diff --git a/doc/paddle/api/paddle/metric/accuracy_cn.rst b/doc/paddle/api/paddle/metric/accuracy_cn.rst old mode 100755 new mode 100644 index 15c3d9efcb115065c8b41034ecc0d4703ffb1730..0cb6ea087033b21afd2cea5838f6d1366868b92f --- a/doc/paddle/api/paddle/metric/accuracy_cn.rst +++ b/doc/paddle/api/paddle/metric/accuracy_cn.rst @@ -1,52 +1,63 @@ -.. _cn_api_fluid_layers_accuracy: +.. _cn_api_fluid_metrics_Accuracy: -accuracy +Accuracy ------------------------------- +.. py:class:: paddle.fluid.metrics.Accuracy(name=None) -.. py:function:: paddle.fluid.layers.accuracy(input, label, k=1, correct=None, total=None) +该接口用来计算多个mini-batch的平均准确率。Accuracy对象有两个状态value和weight。Accuracy的定义参照 https://en.wikipedia.org/wiki/Accuracy_and_precision 。 -accuracy layer。 参考 https://en.wikipedia.org/wiki/Precision_and_recall +参数: + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -使用输入和标签计算准确率。 如果正确的标签在topk个预测值里，则计算结果加1。注意：输出正确率的类型由input类型决定，input和lable的类型可以不一样。 +返回：初始化后的 ``Accuracy`` 对象 -参数： - - **input** (Tensor|LoDTensor)-数据类型为float32,float64。输入为网络的预测值。shape为 ``[sample_number, class_dim]`` 。 - - **label** (Tensor|LoDTensor)-数据类型为int64，int32。输入为数据集的标签。shape为 ``[sample_number, 1]`` 。 - - **k** (int64|int32) - 取每个类别中k个预测值用于计算。 - - **correct** (int64|int32)-正确预测值的个数。 - - **total** (int64|int32)-总共的预测值。 - -返回: 计算出来的正确率。 - -返回类型: Variable（Tensor），数据类型为float32的Tensor +返回类型：Accuracy **代码示例** .. code-block:: python - import paddle.fluid as fluid - import numpy as np - - data = fluid.layers.data(name="input", shape=[-1, 32, 32], dtype="float32") - label = fluid.layers.data(name="label", shape=[-1,1], dtype="int") - fc_out = fluid.layers.fc(input=data, size=10) - predict = fluid.layers.softmax(input=fc_out) - result = fluid.layers.accuracy(input=predict, label=label, k=5) - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - - exe.run(fluid.default_startup_program()) - x = np.random.rand(3, 32, 32).astype("float32") - y = np.array([[1],[0],[1]]) - output= exe.run(feed={"input": x,"label": y}, - fetch_list=[result[0]]) - print(output) - - """ - Output: - [array([0.6666667], dtype=float32)] - """ + import paddle.fluid as fluid + # 假设有batch_size = 128 + batch_size=128 + accuracy_manager = fluid.metrics.Accuracy() + # 假设第一个batch的准确率为0.9 + batch1_acc = 0.9 + accuracy_manager.update(value = batch1_acc, weight = batch_size) + print("expect accuracy: %.2f, get accuracy: %.2f" % (batch1_acc, accuracy_manager.eval())) + # 假设第二个batch的准确率为0.8 + batch2_acc = 0.8 + accuracy_manager.update(value = batch2_acc, weight = batch_size) + #batch1和batch2的联合准确率为(batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2 + print("expect accuracy: %.2f, get accuracy: %.2f" % ((batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2, accuracy_manager.eval())) + #重置accuracy_manager + accuracy_manager.reset() + #假设第三个batch的准确率为0.8 + batch3_acc = 0.8 + accuracy_manager.update(value = batch3_acc, weight = batch_size) + print("expect accuracy: %.2f, get accuracy: %.2f" % (batch3_acc, accuracy_manager.eval())) + +.. py:method:: update(value, weight) + +该函数使用输入的(value, weight)来累计更新Accuracy对象的对应状态，更新方式如下： + + .. math:: + \\ \begin{array}{l}{\text { self. value }+=\text { value } * \text { weight }} \\ {\text { self. weight }+=\text { weight }}\end{array} \\ + +参数： + - **value** (float|numpy.array) – mini-batch的正确率 + - **weight** (int|float) – mini-batch的大小 + +返回：无 + +.. py:method:: eval() + +该函数计算并返回累计的mini-batches的平均准确率。 + +返回：累计的mini-batches的平均准确率 + +返回类型：float或numpy.array + diff --git a/doc/paddle/api/paddle/metric/auc_cn.rst b/doc/paddle/api/paddle/metric/auc_cn.rst old mode 100755 new mode 100644 index e915875f5d306abdf7ebf51cc65a2cbdf66ca5de..8e6b7bfea5ec381b7af051ba39fc080291b4fcba --- a/doc/paddle/api/paddle/metric/auc_cn.rst +++ b/doc/paddle/api/paddle/metric/auc_cn.rst @@ -1,43 +1,25 @@ -.. _cn_api_fluid_layers_auc: +.. _cn_api_fluid_metrics_Auc: -auc +Auc ------------------------------- +.. py:class:: paddle.fluid.metrics.Auc(name, curve='ROC', num_thresholds=4095) -.. py:function:: paddle.fluid.layers.auc(input, label, curve='ROC', num_thresholds=200, topk=1, slide_steps=1) +**注意**：目前只用Python实现Auc，可能速度略慢 -**Area Under the Curve(AUC) Layer** +该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。 -该层根据前向输出和标签计算AUC，在二分类(binary classification)估计中广泛使用。 +该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。 -注：如果输入标注包含一种值，只有0或1两种情况，数据类型则强制转换成布尔值。相关定义可以在这里: https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 找到 - -有两种可能的曲线： - -1. ROC:受试者工作特征曲线 +参数： + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + - **curve** (str) - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。 -2. PR:准确率召回率曲线 +返回：初始化后的 ``Auc`` 对象 -参数： - - **input** (Tensor|LoDTensor) - 数据类型为float32，float64。浮点二维变量，值的范围为[0,1]。每一行降序排列。该输入为网络预测值的输入。 - - **label** (Tensor|LoDTensor) - 数据类型为int32，int64。二维整型变量，为训练数据的标签。 - - **curve** (str) - 曲线类型，可以为 ``ROC`` 或 ``PR``，默认 ``ROC``。 - - **num_thresholds** (int) - 将roc曲线离散化时使用的临界值数。默认200。 - - **topk** (int) - 取topk的输出值用于计算。 - - **slide_steps** (int) - 当计算batch auc时，不仅用当前步也用于先前步。slide_steps=1，表示用当前步；slide_steps = 3表示用当前步和前两步；slide_steps = 0，则用所有步。 - -返回：代表当前AUC的一个元组。 -返回的元组为auc_out, batch_auc_out, [batch_stat_pos, batch_stat_neg, stat_pos, stat_neg]。 -auc_out为准确率的结果。 -batch_auc_out为batch准确率的结果。 -batch_stat_pos为batch计算时label=1的统计值 -batch_stat_neg为batch计算时label=0的统计值 -stat_pos计算时label=1的统计值 -stat_neg为计算时label=0的统计值 - -返回类型： Variable（Tensor），数据类型为float32或float64的Tensor。 +返回类型：Auc **代码示例**： @@ -45,25 +27,41 @@ stat_neg为计算时label=0的统计值 import paddle.fluid as fluid import numpy as np + # 初始化auc度量 + auc_metric = fluid.metrics.Auc("ROC") + + # 假设batch_size为128 + batch_num = 100 + batch_size = 128 + + for batch_id in range(batch_num): + + class0_preds = np.random.random(size = (batch_size, 1)) + class1_preds = 1 - class0_preds + + preds = np.concatenate((class0_preds, class1_preds), axis=1) + + labels = np.random.randint(2, size = (batch_size, 1)) + auc_metric.update(preds = preds, labels = labels) + + # 应为一个接近0.5的值，因为preds是随机指定的 + print("auc for iteration %d is %.2f" % (batch_id, auc_metric.eval())) + +.. py:method:: update(preds, labels) + +用给定的预测值和标签更新Auc曲线。 + +参数： + - **preds** (numpy.array) - 维度为[batch_size, 2]，preds[i][j]表示将实例i划分为类别j的概率。 + - **labels** (numpy.array) - 维度为[batch_size, 1]，labels[i]为0或1，代表实例i的标签。 + +返回：无 + +.. py:method:: eval() + +该函数计算并返回Auc值。 - data = fluid.layers.data(name="input", shape=[-1, 32,32], dtype="float32") - label = fluid.layers.data(name="label", shape=[1], dtype="int") - fc_out = fluid.layers.fc(input=data, size=2) - predict = fluid.layers.softmax(input=fc_out) - result=fluid.layers.auc(input=predict, label=label) - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - - exe.run(fluid.default_startup_program()) - x = np.random.rand(3,32,32).astype("float32") - y = np.array([1,0,1]) - output= exe.run(feed={"input": x,"label": y}, - fetch_list=[result[0]]) - print(output) - """ - output: - [array([0.5])] - """ +返回：Auc值 +返回类型：float diff --git a/doc/paddle/api/paddle/nn/GRUCell_cn.rst b/doc/paddle/api/paddle/nn/GRUCell_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a714757be122b2c7dd2cd936f809725991807996 --- /dev/null +++ b/doc/paddle/api/paddle/nn/GRUCell_cn.rst @@ -0,0 +1,66 @@ +.. _cn_api_fluid_layers_GRUCell: + +GRUCell +------------------------------- + + +.. py:class:: paddle.fluid.layers.GRUCell(hidden_size, param_attr=None, bias_attr=None, gate_activation=None, activation=None, dtype="float32", name="GRUCell") + +:api_attr: 声明式编程模式（静态图) + + + +门控循环单元（Gated Recurrent Unit）。通过对 :code:`fluid.contrib.layers.rnn_impl.BasicGRUUnit` 包装，来让它可以应用于RNNCell。 + +公式如下： + +.. math:: + u_t & = act_g(W_{ux}x_{t} + W_{uh}h_{t-1} + b_u)\\ + r_t & = act_g(W_{rx}x_{t} + W_{rh}h_{t-1} + b_r)\\ + \tilde{h_t} & = act_c(W_{cx}x_{t} + W_{ch}(r_t \odot h_{t-1}) + b_c)\\ + h_t & = u_t \odot h_{t-1} + (1-u_t) \odot \tilde{h_t} + +更多细节可以参考 `Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation `_ + +参数： + - **hidden_size** (int) - GRUCell中的隐藏层大小。 + - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 + - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **gate_activation** (function，可选) - :math:`act_g` 的激活函数。 默认值为 :code:`fluid.layers.sigmoid`。 + - **activation** (function，可选) - :math:`act_c` 的激活函数。 默认值为 :code:`fluid.layers.tanh` + - **dtype** (string，可选) - 此cell中使用的数据类型。 默认为"float32"。 + - **name** (string，可选) - 用于标识参数和偏差的名称域。 + +返回：GRUCell类的实例对象。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid.layers as layers + cell = layers.GRUCell(hidden_size=256) + + +.. py:method:: call(inputs, states) + +执行GRU的计算。 + +参数： + - **input** (Variable) - 输入，形状为 :math:`[batch\_size，input\_size]` 的tensor，对应于公式中的 :math:`x_t` 。数据类型应为float32。 + - **states** (Variable) - 状态，形状为 :math:`[batch\_size，hidden\_size]` 的tensor。 对应于公式中的 :math:`h_{t-1}` 。数据类型应为float32。 + +返回：一个元组 :code:`(outputs, new_states)` ，其中 :code:`outputs` 和 :code:`new_states` 是同一个tensor，其形状为 :math:`[batch\_size，hidden\_size]`，数据类型和 :code:`state` 的数据类型相同，对应于公式中的 :math:`h_t`。 + +返回类型：tuple + +.. py:method:: state_shape() + +GRUCell的 :code:`state_shape` 是形状 :math:`[hidden\_size]` （batch大小为-1，自动插入到形状中），对应于 :math:`h_{t-1}` 的形状。 + +参数：无。 + +返回：GRUCell的 :code:`state_shape`。 + +返回类型：Variable + + diff --git a/doc/paddle/api/paddle/nn/LSTMCell_cn.rst b/doc/paddle/api/paddle/nn/LSTMCell_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..183dd4ff210000f8c9138d18d402d431d245dd86 --- /dev/null +++ b/doc/paddle/api/paddle/nn/LSTMCell_cn.rst @@ -0,0 +1,67 @@ +.. _cn_api_fluid_layers_LSTMCell: + +LSTMCell +------------------------------- + + + +.. py:class:: paddle.fluid.layers.LSTMCell(hidden_size, param_attr=None, bias_attr=None, gate_activation=None, activation=None, forget_bias=1.0, dtype="float32", name="LSTMCell") + +:api_attr: 声明式编程模式（静态图) + + + +长短期记忆单元（Long-Short Term Memory）。通过对 :code:`fluid.contrib.layers.rnn_impl.BasicLSTMUnit` 包装，来让它可以应用于RNNCell。 + +公式如下： + +.. math:: + i_{t} &= act_g \left ( W_{x_{i}}x_{t}+W_{h_{i}}h_{t-1}+b_{i} \right ) \\ + f_{t} &= act_g \left ( W_{x_{f}}x_{t}+W_{h_{f}}h_{t-1}+b_{f}+forget\_bias \right ) \\ + c_{t} &= f_{t}c_{t-1}+i_{t}act_h\left ( W_{x_{c}}x_{t} +W_{h_{c}}h_{t-1}+b_{c}\right ) \\ + o_{t} &= act_g\left ( W_{x_{o}}x_{t}+W_{h_{o}}h_{t-1}+b_{o} \right ) \\ + h_{t} &= o_{t}act_h \left ( c_{t} \right ) + +更多细节可以参考 `RECURRENT NEURAL NETWORK REGULARIZATION `_ + +参数： + - **hidden_size** (int) - LSTMCell中的隐藏层大小。 + - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 + - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **gate_activation** (function，可选) - :math:`act_g` 的激活函数。 默认值为 :code:`fluid.layers.sigmoid`。 + - **activation** (function，可选) - :math:`act_c` 的激活函数。 默认值为 :code:`fluid.layers.tanh`。 + - **forget_bias** (float，可选) - 计算遗忘们时使用的遗忘偏置。默认值为 1.0。 + - **dtype** (string，可选) - 此Cell中使用的数据类型。 默认值为 `float32`。 + - **name** (string，可选) - 用于标识参数和偏差的名称域。 + +返回：LSTMCell类的实例对象。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid.layers as layers + cell = layers.LSTMCell(hidden_size=256) + + +.. py:method:: call(inputs, states) + +执行GRU的计算。 + +参数： + - **input** (Variable) - 输入，形状为 :math:`[batch\_size，input\_size]` 的tensor，对应于公式中的 :math:`x_t`。数据类型应为float32。 + - **states** (Variable) - 状态，包含两个tensor的列表，每个tensor形状为 :math:`[batch\_size，hidden\_size]`。 对应于公式中的 :math:`h_{t-1}, c_{t-1}`。数据类型应为float32。 + +返回：一个元组 :code:`(outputs, new_states)`，其中 :code:`outputs` 是形状为 :math:`[batch\_size，hidden\_size]` 的tensor，对应于公式中的 :math:`h_{t}`；:code:`new_states` 是一个列表，包含形状为 :math:`[batch_size，hidden_size]` 的两个tensor变量，它们对应于公式中的 :math:`h_{t}, c_{t}`。这些tensor的数据类型都与 :code:`state` 的数据类型相同。 + +返回类型：tuple + +.. py:method:: state_shape() + +LSTMCell的 :code:`state_shape` 是一个具有两个形状的列表：:math:`[[hidden\_size], [hidden\_size]]` （batch大小为-1，自动插入到形状中）。 这两个形状分别对应于公式中的 :math:`h_{t-1}` and :math:`c_{t-1}`。 + +参数：无。 + +返回：LSTMCell的 :code:`state_shape` + +返回类型：list diff --git a/doc/paddle/api/paddle/nn/Linear_cn.rst b/doc/paddle/api/paddle/nn/Linear_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..47aef1f7cf3f86d5e02eda4da802a000df8e1483 --- /dev/null +++ b/doc/paddle/api/paddle/nn/Linear_cn.rst @@ -0,0 +1,57 @@ +.. _cn_api_fluid_dygraph_Linear: + +Linear +------------------------------- + +.. py:class:: paddle.nn.Linear(input_dim, output_dim, param_attr=None, bias_attr=None, act=None, dtype='float32') + + +**线性变换层：** + +.. math:: + + \\Out = Act({XW + b})\\ + +其中，:math:`X` 为输入的 Tensor， :math:`W` 和 :math:`b` 分别为权重和偏置。 + +Linear 层只接受一个 Tensor 的输入。 +Linear 层将输入 Tensor 与权重矩阵 :math:`W` 相乘，然后生成形状为 :math:`[N，*，output_dim]` 的输出张量， +其中 :math:`N` 是批量大小，:math:`*` 表示任意数量的附加尺寸。 +如果 bias_attr 不是 None，则将创建一个 bias 变量并将其添加到输出中。 +最后，如果激活 act 不是 None，则相应激活函数也将应用于输出上。 + +参数: + - **input_dim** (int) – 线性变换层输入单元的数目。 + - **output_dim** (int) – 线性变换层输出单元的数目。 + - **param_attr** (ParamAttr, 可选) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr, 可选) – 指定偏置参数属性的对象，若 `bias_attr` 为bool类型，如果设置为False，表示不会为该层添加偏置；如果设置为True，表示使用默认的偏置参数属性。默认值为None，表示使用默认的偏置参数属性。默认的偏置参数属性将偏置参数的初始值设为0。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **act** (str, 可选) – 应用于输出上的激活函数，如tanh、softmax、sigmoid，relu等，支持列表请参考 :ref:`api_guide_activations` ，默认值为None。 + - **dtype** (str, 可选) – 权重的数据类型，可以为float32或float64。默认为float32。 + +返回：无 + +**代码示例** + +.. code-block:: python + + from paddle.fluid.dygraph.base import to_variable + import paddle + import paddle.fluid as fluid + import numpy as np + + data = np.random.uniform( -1, 1, [30, 10, 32] ).astype('float32') + with fluid.dygraph.guard(): + linear = paddle.nn.Linear(32, 64) + data = to_variable(data) + res = linear(data) # [30, 10, 64] + +属性 +:::::::::::: +.. py:attribute:: weight + +本层的可学习参数，类型为 ``Parameter`` + +.. py:attribute:: bias + +本层的可学习偏置，类型为 ``Parameter`` + diff --git a/doc/paddle/api/paddle/nn/functional/activation/elu_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/elu_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c0cf22a5123d75696dc8bdbd7fb78e2d33314c0c --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/elu_cn.rst @@ -0,0 +1,44 @@ +.. _cn_api_nn_cn_elu: + +elu +------------------------------- + +.. py:function:: paddle.nn.functional.elu(x, alpha=1.0, name=None) + +elu激活层（ELU Activation Operator） + +根据 `Exponential Linear Units `_ 对输入Tensor中每个元素应用以下计算。 + +.. math:: + + elu(x) = max(0, x) + min(0, \alpha * (e^{x} − 1)) + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - alpha (float, 可选) - elu的alpha值，默认值为1.0。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([[-1,6],[1,15.6]])) + out = F.elu(x, alpha=0.2) + # [[-0.12642411 6. ] + # [ 1. 15.6 ]] + + diff --git a/doc/paddle/api/paddle/nn/functional/activation/gelu_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/gelu_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..586cd3677d7fddeeddccb47df01b46125dddba08 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/gelu_cn.rst @@ -0,0 +1,48 @@ +.. _cn_api_nn_cn_gelu: + +gelu +------------------------------- + +.. py:function:: paddle.nn.functional.gelu(x, approximate=False, name=None) + +gelu激活层（GELU Activation Operator） + +逐元素计算 gelu激活函数。更多细节请参考 `Gaussian Error Linear Units `_ 。 + +如果使用近似计算： + +.. math:: + gelu(x) = 0.5 * x * (1 + tanh(\sqrt{\frac{2}{\pi}} * (x + 0.044715x^{3}))) + +如果不使用近似计算： + +.. math:: + gelu(x) = 0.5 * x * (1 + erf(\frac{x}{\sqrt{2}})) + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - approximate (bool, 可选) - 是否使用近似计算，默认值为 False，表示不使用近似计算。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([[-1, 0.5],[1, 1.5]])) + out1 = F.gelu(x) # [-0.158655 0.345731 0.841345 1.39979] + out2 = F.gelu(x, True) # [-0.158808 0.345714 0.841192 1.39957] + diff --git a/doc/paddle/api/paddle/nn/functional/activation/hardshrink_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/hardshrink_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..66c492e749c5992f8f86bd06c6d521330b67c7ac --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/hardshrink_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_nn_cn_hard_shrink: + +hardshrink +------------------------------- +.. py:function:: paddle.nn.functional.hardshrink(x, threshold=0.5, name=None) + +hardshrink激活层。计算公式如下： + +.. math:: + + hardshrink(x)= + \left\{ + \begin{aligned} + &x, & & if \ x > threshold \\ + &x, & & if \ x < -threshold \\ + &0, & & if \ others + \end{aligned} + \right. + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - threshold (float, 可选) - hard_shrink激活计算公式中的threshold值。默认值为0.5。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_variable(np.array([-1, 0.3, 2.5])) + out = F.hardshrink(x) # [-1., 0., 2.5] diff --git a/doc/paddle/api/paddle/nn/functional/activation/hardtanh_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/hardtanh_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..fa18b323674f9f5f9fac51b41f32c804b2c1852b --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/hardtanh_cn.rst @@ -0,0 +1,45 @@ +.. _cn_api_nn_cn_hardtanh: + +hardtanh +------------------------------- +.. py:function:: paddle.nn.functional.hardtanh(x, min=-1.0, max=1.0, name=None): + +hardtanh激活层（Hardtanh Activation Operator）。计算公式如下： + +.. math:: + + hardtanh(x)= + \left\{ + \begin{aligned} + &max, & & if \ x > max \\ + &min, & & if \ x < min \\ + &x, & & if \ others + \end{aligned} + \right. + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - min (float, 可选) - hardtanh激活计算公式中的min值。默认值为-1。 + - max (float, 可选) - hardtanh激活计算公式中的max值。默认值为1。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-1.5, 0.3, 2.5])) + out = F.hardtanh(x) # [-1., 0.3, 1.] diff --git a/doc/paddle/api/paddle/nn/functional/activation/leaky_relu_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/leaky_relu_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a0bb19d6ec7f383294f7943389fdd962a6d94bbb --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/leaky_relu_cn.rst @@ -0,0 +1,43 @@ +.. _cn_api_nn_cn_leaky_relu: + +leaky_relu +------------------------------- +.. py:function:: paddle.nn.functional.leaky_relu(x, negative_slope=0.01, name=None) + +leaky_relu激活层。计算公式如下： + +.. math:: + + LeakyReLU(x)= + \left\{ + \begin{aligned} + &x, & & if \ x >= 0 \\ + &negative\_slope * x, & & otherwise \\ + \end{aligned} + \right. \\ + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。 + - negative_slope (float，可选) - :math:`x < 0` 时的斜率。默认值为0.01。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-2, 0, 1], 'float32')) + out = F.leaky_relu(x) # [-0.02, 0., 1.] diff --git a/doc/paddle/api/paddle/nn/functional/activation/log_softmax_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/log_softmax_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..5509a6a4f18b928ffa4426b7bedfda88926f5017 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/log_softmax_cn.rst @@ -0,0 +1,51 @@ +.. _cn_api_nn_cn_log_softmax: + +log_softmax +------------------------------- +.. py:function:: paddle.nn.functional.log_softmax(x, axis=-1, dtype=None, name=None) + +该OP实现了log_softmax层。OP的计算公式如下： + +.. math:: + + Out[i, j] = log(softmax(x)) = log(\frac{\exp(X[i, j])}{\sum_j(exp(X[i, j])}) + +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - axis (int, 可选) - 指定对输入 ``x`` 进行运算的轴。``axis`` 的有效范围是[-D, D)，D是输入 ``x`` 的维度， ``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。 + - dtype (str|np.dtype|core.VarDesc.VarType, 可选) - 输入Tensor的数据类型。如果指定了 ``dtype`` ，则输入Tensor的数据类型会在计算前转换到 ``dtype`` 。``dtype``可以用来避免数据溢出。如果 ``dtype`` 为None，则输出Tensor的数据类型和 ``x`` 相同。默认值为None。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，形状和 ``x`` 相同，数据类型为 ``dtype`` 或者和 ``x`` 相同。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = np.array([[[-2.0, 3.0, -4.0, 5.0], + [3.0, -4.0, 5.0, -6.0], + [-7.0, -8.0, 8.0, 9.0]], + [[1.0, -2.0, -3.0, 4.0], + [-5.0, 6.0, 7.0, -8.0], + [6.0, 7.0, 8.0, 9.0]]]).astype('float32') + x = paddle.to_tensor(x) + out1 = F.log_softmax(x) + out2 = F.log_softmax(x, dtype='float64') + # out1's data type is float32; out2's data type is float64 + # out1 and out2's value is as follows: + # [[[ -7.1278396 -2.1278396 -9.127839 -0.12783948] + # [ -2.1270514 -9.127051 -0.12705144 -11.127051 ] + # [-16.313261 -17.313261 -1.3132617 -0.31326184]] + # [[ -3.0518122 -6.051812 -7.051812 -0.051812 ] + # [-12.313267 -1.3132664 -0.3132665 -15.313267 ] + # [ -3.4401896 -2.4401896 -1.4401896 -0.44018966]]] diff --git a/doc/paddle/api/paddle/nn/functional/activation/logsigmoid_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/logsigmoid_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..5296f5197e8051d67f87bd7b453a335c5c3b6117 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/logsigmoid_cn.rst @@ -0,0 +1,37 @@ +.. _cn_api_nn_cn_logsigmoid: + +logsigmoid +------------------------------- + +.. py:function:: paddle.nn.functional.logsigmoid(x, name=None) + +logsigmoid激活层。计算公式如下： + +.. math:: + + logsigmoid(x) = \log \frac{1}{1 + e^{-x}} + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([1.0, 2.0, 3.0, 4.0])) + out = F.logsigmoid(x) # [-0.313262 -0.126928 -0.0485874 -0.0181499] diff --git a/doc/paddle/api/paddle/nn/functional/activation/prelu_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/prelu_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..caa1681a91964f84679793a7a795a812bc839a2a --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/prelu_cn.rst @@ -0,0 +1,50 @@ +.. _cn_api_nn_cn_prelu: + +prelu +------------------------------- +.. py:function:: paddle.nn.functional.prelu(x, weight, name=None): + +prelu激活层（PRelu Activation Operator）。计算公式如下： + +.. math:: + + prelu(x) = max(0, x) + weight * min(0, x) + +其中，:math:`x` 和 `weight` 为输入的 Tensor + +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - weight (Tensor) - 可训练参数，数据类型同``x`` 一致，形状支持2种：[1] 或者 [in]，其中`in`为输入的通道数。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + data = np.array([[[[-2.0, 3.0, -4.0, 5.0], + [ 3.0, -4.0, 5.0, -6.0], + [-7.0, -8.0, 8.0, 9.0]], + [[ 1.0, -2.0, -3.0, 4.0], + [-5.0, 6.0, 7.0, -8.0], + [ 6.0, 7.0, 8.0, 9.0]]]], 'float32') + x = paddle.to_tensor(data) + w = paddle.to_tensor(np.array([0.25]).astype('float32')) + out = F.prelu(x, w) + # [[[[-0.5 , 3. , -1. , 5. ], + # [ 3. , -1. , 5. , -1.5 ], + # [-1.75, -2. , 8. , 9. ]], + # [[ 1. , -0.5 , -0.75, 4. ], + # [-1.25, 6. , 7. , -2. ], + # [ 6. , 7. , 8. , 9. ]]]] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/functional/activation/relu6_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/relu6_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..b4c98f8fce5e63674f35bda7951018e9eb2d1fa7 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/relu6_cn.rst @@ -0,0 +1,37 @@ +.. _cn_api_nn_cn_relu6: + +relu6 +------------------------------- + +.. py:function:: paddle.nn.functional.relu6(x, name=None) + +relu6激活层 + +.. math:: + + relu6(x) = min(max(0,x), 6) + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-1, 0.3, 6.5])) + out = F.relu6(x) # [0, 0.3, 6] diff --git a/doc/paddle/api/paddle/nn/functional/activation/relu_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/relu_cn.rst index 6df2e05bea36cf96f6990269d6bb77952f15549e..447d0bb01514d42aa74f6265d52cd8ed42c40880 100644 --- a/doc/paddle/api/paddle/nn/functional/activation/relu_cn.rst +++ b/doc/paddle/api/paddle/nn/functional/activation/relu_cn.rst @@ -1,37 +1,38 @@ -.. _cn_api_fluid_layers_relu: +.. _cn_api_nn_cn_relu: relu ------------------------------- -.. py:function:: paddle.fluid.layers.relu(x, name=None) +.. py:function:: paddle.nn.functional.relu(x, name=None) +relu激活层（Rectified Linear Unit）。计算公式如下： +.. math:: + relu(x) = max(0, x) -ReLU（Rectified Linear Unit）激活函数 +其中，:math:`x` 为输入的 Tensor -.. math:: Out=max(0,x) +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -参数: - - **x** (Variable) - 输入的多维 ``Tensor`` ，数据类型为：float32、float64。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 -返回: 与 ``x`` 维度相同、数据类型相同的 ``Tensor`` 。 +代码示例 +:::::::::: -返回类型: Variable +.. code-block:: python -**代码示例**: + import paddle + import paddle.nn.functional as F + import numpy as np -.. code-block:: python + paddle.disable_static() - import paddle.fluid as fluid - import numpy as np - - in1 = np.array([[-1,0],[1,2.6]]) - with fluid.dygraph.guard(): - x1 = fluid.dygraph.to_variable(in1) - out1 = fluid.layers.relu(x1) - print(out1.numpy()) - # [[0. 0. ] - # [1. 2.6]] + x = paddle.to_tensor(np.array([-2, 0, 1]).astype('float32')) + out = F.relu(x) # [0., 0., 1.] diff --git a/doc/paddle/api/paddle/nn/functional/activation/selu_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/selu_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a52d54bad21e955dbbd74dcd853d54aae32e1a56 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/selu_cn.rst @@ -0,0 +1,43 @@ +.. _cn_api_nn_cn_selu: + +selu +------------------------------- + +.. py:function:: paddle.nn.functional.selu(x, scale=1.0507009873554804934193349852946, alpha=1.6732632423543772848170429916717, name=None) + +selu激活层 + +.. math:: + + selu(x)= scale * + \begin{cases} + x, \text{if } x > 0 \\ + alpha * e^{x} - alpha, \text{if } x <= 0 + \end{cases} + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - scale (float, 可选) - selu激活计算公式中的scale值，必须大于1.0。默认值为1.0507009873554804934193349852946。 + - alpha (float, 可选) - selu激活计算公式中的alpha值，必须大于等于零。默认值为1.6732632423543772848170429916717。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([[0.0, 1.0],[2.0, 3.0]])) + out = F.selu(x) # [[0, 1.050701],[2.101402, 3.152103]] diff --git a/doc/paddle/api/paddle/nn/functional/activation/softmax_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/softmax_cn.rst old mode 100755 new mode 100644 index a11f955072ab19183abde10ce55469e81bc1c696..74b1605f2b433c57bfae76b4629341450d451677 --- a/doc/paddle/api/paddle/nn/functional/activation/softmax_cn.rst +++ b/doc/paddle/api/paddle/nn/functional/activation/softmax_cn.rst @@ -1,23 +1,17 @@ -.. _cn_api_fluid_layers_softmax: +.. _cn_api_nn_cn_softmax: softmax ------------------------------- - -.. py:function:: paddle.fluid.layers.softmax(input, use_cudnn=False, name=None, axis=-1) - -:alias_main: paddle.nn.functional.softmax -:alias: paddle.nn.functional.softmax,paddle.nn.functional.activation.softmax -:old_api: paddle.fluid.layers.softmax - +.. py:function:: paddle.nn.functional.softmax(x, axis=-1, dtype=None, name=None) 该OP实现了softmax层。OP的计算过程如下： -步骤1：输入 ``input`` 的 ``axis`` 维会被置换到最后一维； +步骤1：输入 ``x`` 的 ``axis`` 维会被置换到最后一维； -步骤2：将输入 ``Tensor`` 在逻辑上变换为二维矩阵。二维矩阵第一维（列长度）是输入除最后一维之外的其他维度值的乘积，第二维（行长度）和输入 ``axis`` 维的长度相同；对于矩阵的每一行，softmax操作对其进行重新缩放，使得该行的每个元素在 \[0,1\] 范围内，并且总和为1； +步骤2：将输入 ``x`` 在逻辑上变换为二维矩阵。二维矩阵第一维（列长度）是输入除最后一维之外的其他维度值的乘积，第二维（行长度）和输入 ``axis`` 维的长度相同；对于矩阵的每一行，softmax操作对其进行重新缩放，使得该行的每个元素在 \[0,1\] 范围内，并且总和为1； -步骤3：softmax操作执行完成后，执行步骤1和步骤2的逆运算，将二维矩阵恢复至和输入 ``input`` 相同的维度。 +步骤3：softmax操作执行完成后，执行步骤1和步骤2的逆运算，将二维矩阵恢复至和输入 ``x`` 相同的维度。 上述步骤2中softmax操作计算过程如下： @@ -29,18 +23,17 @@ softmax .. math:: - - Out[i,j] = \frac{exp(X[i,j])}{\sum_j exp(X[i,j])} + softmax[i, j] = \frac{\exp(x[i, j])}{\sum_j(exp(x[i, j])} - 示例1（矩阵一共有三维。axis = -1，表示沿着最后一维（即第三维）做softmax操作） -.. code-block:: python +.. code-block:: text - 输入 + # input - X.shape = [2, 3, 4] + x.shape = [2, 3, 4] - X.data = [[[2.0, 3.0, 4.0, 5.0], + x.data = [[[2.0, 3.0, 4.0, 5.0], [3.0, 4.0, 5.0, 6.0], [7.0, 8.0, 8.0, 9.0]], [[1.0, 2.0, 3.0, 4.0], @@ -49,11 +42,11 @@ softmax axis = -1 - 输出 + # output - Out.shape = [2, 3, 4] + out.shape = [2, 3, 4] - Out.data = [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + out.data = [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426], [0.0320586 , 0.08714432, 0.23688282, 0.64391426], [0.07232949, 0.19661193, 0.19661193, 0.53444665]], [[0.0320586 , 0.08714432, 0.23688282, 0.64391426], @@ -62,13 +55,13 @@ softmax - 示例2（矩阵一共有三维。axis = 1，表示沿着第二维做softmax操作） -.. code-block:: python +.. code-block:: text - 输入 + # input - X.shape = [2, 3, 4] + x.shape = [2, 3, 4] - X.data = [[[2.0, 3.0, 4.0, 5.0], + x.data = [[[2.0, 3.0, 4.0, 5.0], [3.0, 4.0, 5.0, 6.0], [7.0, 8.0, 8.0, 9.0]], [[1.0, 2.0, 3.0, 4.0], @@ -77,11 +70,11 @@ softmax axis = 1 - 输出 + # output - Out.shape = [2, 3, 4] + out.shape = [2, 3, 4] - Out.data = [[[0.00657326, 0.00657326, 0.01714783, 0.01714783], + out.data = [[[0.00657326, 0.00657326, 0.01714783, 0.01714783], [0.01786798, 0.01786798, 0.04661262, 0.04661262], [0.97555875, 0.97555875, 0.93623955, 0.93623955]], [[0.00490169, 0.00490169, 0.00490169, 0.00490169], @@ -89,30 +82,42 @@ softmax [0.72747516, 0.72747516, 0.72747516, 0.72747516]]] -参数： - - **input** (Variable) - 任意维度的多维 ``Tensor`` ，数据类型为float32或float64。 - - **use_cudnn** (bool, 可选) - 指示是否用cudnn库。当 ``use_cudnn`` 为True时，在安装GPU版本Paddle并且本机安装cudnn库的前提下，使用GPU训练或推理时才有效。默认值：False。 - - **name** (str, 可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - - **axis** (int, 可选) - 指示进行softmax计算的维度索引，其范围应为 :math:`[-1，rank-1]` ，其中rank是输入变量的秩。默认值：-1（表示对最后一维做softmax操作）。 +参数 +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - axis (int, 可选) - 指定对输入 ``x`` 进行运算的轴。``axis`` 的有效范围是[-D, D)，D是输入 ``x`` 的维度， ``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。 + - dtype (str|np.dtype|core.VarDesc.VarType, 可选) - 输入Tensor的数据类型。如果指定了 ``dtype`` ，则输入Tensor的数据类型会在计算前转换到 ``dtype`` 。``dtype``可以用来避免数据溢出。如果 ``dtype`` 为None，则输出Tensor的数据类型和 ``x`` 相同。默认值为None。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回：表示softmax操作结果的 ``Tensor`` ，数据类型和 ``input`` 一致，返回维度和 ``input`` 一致。 +返回 +:::::::::: + ``Tensor`` ，形状和 ``x`` 相同，数据类型为 ``dtype`` 或者和 ``x`` 相同。 -返回类型：Variable - -**代码示例** +代码示例 +:::::::::: .. code-block:: python - import paddle.fluid as fluid + import paddle + import paddle.nn.functional as F import numpy as np - data = fluid.layers.data(name="input", shape=[-1, 3],dtype="float32") - result = fluid.layers.softmax(data,axis=1) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - x = np.random.rand(3, 3).astype("float32") - output= exe.run(feed={"input": x}, - fetch_list=[result[0]]) - print(output) - + paddle.disable_static() + + x = np.array([[[2.0, 3.0, 4.0, 5.0], + [3.0, 4.0, 5.0, 6.0], + [7.0, 8.0, 8.0, 9.0]], + [[1.0, 2.0, 3.0, 4.0], + [5.0, 6.0, 7.0, 8.0], + [6.0, 7.0, 8.0, 9.0]]], 'float32') + x = paddle.to_tensor(x) + out1 = F.softmax(x) + out2 = F.softmax(x, dtype='float64') + # out1's data type is float32; out2's data type is float64 + # out1 and out2's value is as follows: + # [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.07232949, 0.19661193, 0.19661193, 0.53444665]], + # [[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.0320586 , 0.08714432, 0.23688282, 0.64391426]]] diff --git a/doc/paddle/api/paddle/nn/functional/activation/softplus_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/softplus_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..dabf852e2ade608c739fa9e0900935132c7b7b2d --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/softplus_cn.rst @@ -0,0 +1,40 @@ +.. _cn_api_nn_cn_softplus: + +softplus +------------------------------- + +.. py:function:: paddle.nn.functional.softplus(x, beta=1, threshold=20, name=None) + +softplus激活层 + +.. math:: + + softplus(x) = \frac{1}{beta} * \log(1 + e^{beta * x}) \\ + \text{为了保证数值稳定性, 当}\,beta * x > threshold\,\text{时，函数转变为线性函数x}. + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - beta (float, 可选) - Softplus激活计算公式中的beta值。默认值为1。 + - threshold (float, 可选) - Softplus激活计算公式中的threshold值。默认值为20。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + out = F.softplus(x) # [0.513015, 0.598139, 0.744397, 0.854355] diff --git a/doc/paddle/api/paddle/nn/functional/activation/softshrink_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/softshrink_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d630a80d553919f7814247ac5b6049b1f3146f84 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/softshrink_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_nn_cn_softshrink: + +softshrink +------------------------------- + +.. py:function:: paddle.nn.functional.softshrink(x, threshold=0.5, name=None) + +softshrink激活层 + +.. math:: + + softshrink(x)= \begin{cases} + x - threshold, \text{if } x > threshold \\ + x + threshold, \text{if } x < -threshold \\ + 0, \text{otherwise} + \end{cases} + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - threshold (float, 可选) - softshrink激活计算公式中的threshold值，必须大于等于零。默认值为0.5。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.9, -0.2, 0.1, 0.8])) + out = F.softshrink(x) # [-0.4, 0, 0, 0.3] diff --git a/doc/paddle/api/paddle/nn/functional/activation/softsign_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/softsign_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..24c34bdbd2e89e28cc09e3ce421763afbafda529 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/softsign_cn.rst @@ -0,0 +1,37 @@ +.. _cn_api_nn_cn_softsign: + +softsign +------------------------------- + +.. py:function:: paddle.nn.functional.softsign(x, name=None) + +softsign激活层 + +.. math:: + + softsign(x) = \frac{x}{1 + |x|} + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + out = F.softsign(x) # [-0.285714, -0.166667, 0.0909091, 0.230769] diff --git a/doc/paddle/api/paddle/nn/functional/activation/tanhshrink_cn.rst b/doc/paddle/api/paddle/nn/functional/activation/tanhshrink_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..2e49b2b5156ab0d27298fbeefdc0802061cb09ca --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/activation/tanhshrink_cn.rst @@ -0,0 +1,37 @@ +.. _cn_api_nn_cn_tanhshrink: + +tanhshrink +------------------------------- + +.. py:function:: paddle.nn.functional.tanhshrink(x, name=None) + +tanhshrink激活层 + +.. math:: + + tanhshrink(x) = x - tanh(x) + +其中，:math:`x` 为输入的 Tensor + +参数: +:::::::::: + - x (Tensor) - 输入的 ``Tensor`` ，数据类型为：float32、float64。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::::: + ``Tensor`` ，数据类型和形状同 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + out = F.tanhshrink(x) # [-0.020051, -0.00262468, 0.000332005, 0.00868739] diff --git a/doc/paddle/api/paddle/nn/functional/common/alpha_dropout_cn.rst b/doc/paddle/api/paddle/nn/functional/common/alpha_dropout_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..cad8c3bb7d12fb6a9f9db481103d8e949ca0c688 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/alpha_dropout_cn.rst @@ -0,0 +1,37 @@ +.. _cn_api_nn_functional_alpha_dropout: + +alpha_dropout +------------------------------- + +.. py:function:: paddle.nn.functional.alpha_dropout(x, p=0.5, training=True, name=None) + +alpha_dropout是一种具有自归一化性质的dropout。均值为0，方差为1的输入，经过alpha_dropout计算之后，输出的均值和方差与输入保持一致。alpha_dropout通常与SELU激活函数组合使用。 + +参数 +::::::::: + - **x** (Tensor): 输入的多维 `Tensor` ，数据类型为：float32、float64。 + - **p** (float): 将输入节点置0的概率，即丢弃概率。默认: 0.5。 + - **training** (bool): 标记是否为训练阶段。 默认: True。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +经过alpha_dropout之后的结果，与输入x形状相同的 `Tensor` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.array([[-1, 1], [-1, 1]]).astype('float32') + x = paddle.to_tensor(x) + y_train = paddle.nn.functional.alpha_dropout(x, 0.5) + y_test = paddle.nn.functional.alpha_dropout(x, 0.5, training=False) + print(x.numpy()) + print(y_train.numpy()) + # [[-0.10721093, 1.6655989 ], [-0.7791938, -0.7791938]] (randomly) + print(y_test.numpy()) diff --git a/doc/paddle/api/paddle/nn/functional/common/bilinear_cn.rst b/doc/paddle/api/paddle/nn/functional/common/bilinear_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..6872bd957cd65779d834d2bda44774f9a04e2c36 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/bilinear_cn.rst @@ -0,0 +1,41 @@ +.. _cn_api_nn_functional_bilinear: + +bilinear +------------------------------- + + +.. py:function:: paddle.nn.functional.bilinear(x1, x2, weight, bias=None, name=None) + +该层对两个输入执行双线性张量积。 +详细的计算和返回值维度请参见 :ref:`cn_api_nn_Bilinear` + +参数 +::::::::: + - **x1** (int): 第一个输入的 `Tensor` ，数据类型为：float32、float64。 + - **x2** (int): 第二个输入的 `Tensor` ，数据类型为：float32、float64。 + - **weight** (Parameter) ：本层的可学习参数。形状是 [out_features, in1_features, in2_features]。 + - **bias** (Parameter, 可选) : 本层的可学习偏置。形状是 [1, out_features]。默认值为None，如果被设置成None，则不会有bias加到output结果上。 + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 + +返回 +::::::::: +``Tensor``，一个形为 [batch_size, out_features] 的 2-D 张量。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy + import paddle.nn.functional as F + + paddle.disable_static() + x1 = numpy.random.random((5, 5)).astype('float32') + x2 = numpy.random.random((5, 4)).astype('float32') + w = numpy.random.random((1000, 5, 4)).astype('float32') + b = numpy.random.random((1, 1000)).astype('float32') + + result = F.bilinear(paddle.to_tensor(x1), paddle.to_tensor(x2), paddle.to_tensor(w), paddle.to_tensor(b)) # result shape [5, 1000] + + diff --git a/doc/paddle/api/paddle/nn/functional/common/cosine_similarity_cn.rst b/doc/paddle/api/paddle/nn/functional/common/cosine_similarity_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c2f4109534b5485e5154cc140a1661d94b3945f8 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/cosine_similarity_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_paddle_nn_cosine_similarity: + +cosine_similarity +------------------------------- + +.. py:function:: paddle.nn.functional.cosine_similarity(x1, x2, axis=1, eps=1e-8) + +该OP用于计算x1与x2沿axis维度的余弦相似度。 + +参数： + - **x1** (Tensor) - Tensor，数据类型支持float32, float64。 + - **x2** (Tensor) - Tensor，数据类型支持float32, float64。 + - **axis** (int) - 指定计算的维度，会在该维度上计算余弦相似度，默认值为1。 + - **eps** (float) - 很小的值，防止计算时分母为0，默认值为1e-8。 + + +返回： 余弦相似度的计算结果，数据类型与x1, x2相同。 + +返回类型：Tensor + + + +**代码示例：** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + np.random.seed(0) + x1 = np.random.rand(2,3) + x2 = np.random.rand(2,3) + x1 = paddle.to_tensor(x1) + x2 = paddle.to_tensor(x2) + result = paddle.nn.functional.cosine_similarity(x1, x2, axis=0) + print(result.numpy()) + # [0.99806249 0.9817672 0.94987036] + + + diff --git a/doc/paddle/api/paddle/nn/functional/common/dropout2d_cn.rst b/doc/paddle/api/paddle/nn/functional/common/dropout2d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..35c61c137a4842bc17f7c43eea4eb14d3a595e81 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/dropout2d_cn.rst @@ -0,0 +1,41 @@ +.. _cn_api_nn_functional_dropout2d: + +dropout2d +------------------------------- + +.. py:function:: paddle.nn.functional.dropout2d(x, p=0.5, training=True, name=None) + +该算子根据丢弃概率 `p` ，在训练过程中随机将某些通道特征图置0(对一个形状为 `NCHW` 的4维张量，通道特征图指的是其中的形状为 `HW` 的2维特征图)。 + +.. note:: + 该op基于 ``paddle.nn.functional.dropout`` 实现，如您想了解更多，请参见 :ref:`cn_api_nn_functional_dropout` 。 + +参数 +::::::::: + - **x** (Tensor): 形状为[N, C, H, W]或[N, H, W, C]的4D `Tensor` ，数据类型为float32或float64。 + - **p** (float): 将输入通道置0的概率，即丢弃概率。默认: 0.5。 + - **training** (bool): 标记是否为训练阶段。 默认: True。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +经过dropout2d之后的结果，与输入x形状相同的 `Tensor` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.random.random(size=(2, 3, 4, 5)).astype('float32') + x = paddle.to_tensor(x) + y_train = paddle.nn.functional.dropout2d(x) #train + y_test = paddle.nn.functional.dropout2d(x, training=False) + for i in range(2): + for j in range(3): + print(x.numpy()[i,j,:,:]) + print(y_train.numpy()[i,j,:,:]) + print(y_test.numpy()[i,j,:,:]) diff --git a/doc/paddle/api/paddle/nn/functional/common/dropout3d_cn.rst b/doc/paddle/api/paddle/nn/functional/common/dropout3d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..0fc0ab0ee6a5cf37b81319673b9db8c1c131081c --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/dropout3d_cn.rst @@ -0,0 +1,39 @@ +.. _cn_api_nn_functional_dropout3d: + +dropout3d +------------------------------- + +.. py:function:: paddle.nn.functional.dropout3d(x, p=0.5, training=True, name=None) + +该算子根据丢弃概率 `p` ，在训练过程中随机将某些通道特征图置0(对一个形状为 `NCDHW` 的5维张量，通道指的是其中的形状为 `DHW` 的3维特征图)。 + +.. note:: + 该op基于 ``paddle.nn.functional.dropout`` 实现，如您想了解更多，请参见 :ref:`cn_api_nn_functional_dropout` 。 + +参数 +::::::::: + - **x** (Tensor): 形状为[N, C, D, H, W]或[N, D, H, W, C]的5D `Tensor` ，数据类型为float32或float64。 + - **p** (float): 将输入通道置0的概率，即丢弃概率。默认: 0.5。 + - **training** (bool): 标记是否为训练阶段。 默认: True。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +经过dropout3d之后的结果，与输入x形状相同的 `Tensor` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.random.random(size=(2, 3, 4, 5, 6)).astype('float32') + x = paddle.to_tensor(x) + y_train = paddle.nn.functional.dropout3d(x) #train + y_test = paddle.nn.functional.dropout3d(x, training=False) + print(x.numpy()[0,0,:,:,:]) + print(y_train.numpy()[0,0,:,:,:]) + print(y_test.numpy()[0,0,:,:,:]) diff --git a/doc/paddle/api/paddle/nn/functional/common/dropout_cn.rst b/doc/paddle/api/paddle/nn/functional/common/dropout_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a349e66aeb5471ffe5810e2c5fe480d8f736515e --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/dropout_cn.rst @@ -0,0 +1,134 @@ +.. _cn_api_nn_functional_dropout: + +dropout +------------------------------- + +.. py:function:: paddle.nn.functional.dropout(x, p=0.5, axis=None, training=True, mode="upscale_in_train”, name=None) + +Dropout是一种正则化手段，该算子根据给定的丢弃概率 `p` ，在训练过程中随机将一些神经元输出设置为0，通过阻止神经元节点间的相关性来减少过拟合。 + +参数 +::::::::: + - **x** (Tensor): 输入的多维 `Tensor` ，数据类型为：float32、float64。 + - **p** (float): 将输入节点置0的概率，即丢弃概率。默认: 0.5。 + - **axis** (int|list): 指定对输入 `Tensor` 进行dropout操作的轴。默认: None。 + - **training** (bool): 标记是否为训练阶段。 默认: True。 + - **mode** (str): 丢弃单元的方式，有两种'upscale_in_train'和'downscale_in_infer'，默认: 'upscale_in_train'。计算方法如下: + + 1. upscale_in_train, 在训练时增大输出结果。 + + - train: out = input * mask / ( 1.0 - p ) + - inference: out = input + + 2. downscale_in_infer, 在预测时减小输出结果 + + - train: out = input * mask + - inference: out = input * (1.0 - p) + + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +经过dropout之后的结果，与输入x形状相同的 `Tensor` 。 + +使用示例1 +::::::::: +axis参数的默认值为None。当 ``axis=None`` 时，dropout的功能为: 对输入张量x中的任意元素，以丢弃概率p随机将一些元素输出置0。这是我们最常见的dropout用法。 + + - 下面以一个示例来解释它的实现逻辑，同时展示其它参数的含义。 + +.. code-block:: text + + 假定x是形状为2*3的2维张量: + [[1 2 3] + [4 5 6]] + 在对x做dropout时，程序会先生成一个和x相同形状的mask张量，mask中每个元素的值为0或1。 + 每个元素的具体值，则是依据丢弃概率从伯努利分布中随机采样得到。 + 比如，我们可能得到下面这样一个2*3的mask: + [[0 1 0] + [1 0 1]] + 将输入x和生成的mask点积，就得到了随机丢弃部分元素之后的结果: + [[0 2 0] + [4 0 6]] + 假定dropout的概率使用默认值，即 ``p=0.5`` ，若mode参数使用默认值，即 ``mode='upscale_in_train'`` ， + 则在训练阶段，最终增大后的结果为: + [[0 4 0 ] + [8 0 12]] + 在测试阶段，输出跟输入一致: + [[1 2 3] + [4 5 6]] + 若参数mode设置为'downscale_in_infer'，则训练阶段的输出为: + [[0 2 0] + [4 0 6]] + 在测试阶段，缩小后的输出为: + [[0.5 1. 1.5] + [2. 2.5 3. ]] + +使用示例2 +::::::::: +若参数axis不为None，dropout的功能为：以一定的概率从图像特征或语音序列中丢弃掉整个通道。 + + - axis应设置为: ``[0,1,...,ndim(x)-1]`` 的子集（ndim(x)为输入x的维度），例如: + + - 若x的维度为2，参数axis可能的取值有4种: ``None``, ``[0]``, ``[1]``, ``[0,1]`` + - 若x的维度为3，参数axis可能的取值有8种: ``None``, ``[0]``, ``[1]``, ``[2]``, ``[0,1]``, ``[0,2]``, ``[1,2]``, ``[0,1,2]`` + + - 下面以维度为2的输入张量展示axis参数的用法: + +.. code-block:: text + + 假定x是形状为2*3的2维Tensor: + [[1 2 3] + [4 5 6]] + (1) 若 ``axis=[0]`` ， 则表示只在第0个维度做dropout。这时生成mask的形状为2*1。 + 例如，我们可能会得到这样的mask: + [[1] + [0]] + 这个2*1的mask在和x做点积的时候，会首先广播成一个2*3的矩阵: + [[1 1 1] + [0 0 0]] + 点积所得的结果为: + [[1 2 3] + [0 0 0]] + 之后依据其它参数的设置，得到最终的输出结果。 + + (2) 若 ``axis=[1]`` ，则表示只在第1个维度做dropout。这时生成的mask形状为1*3。 + 例如，我们可能会得到这样的mask: + [[1 0 1]] + 这个1*3的mask在和x做点积的时候，会首先广播成一个2*3的矩阵: + [[1 0 1] + [1 0 1]] + 点积所得结果为: + [[1 0 3] + [4 0 6]] + (3) 若 ``axis=[0, 1]`` ，则表示在第0维和第1维上做dropout。此时与默认设置 ``axis=None`` 的作用一致。 + +若输入x为4维张量，形状为 `NCHW` , 当设置 ``axis=[0,1]`` 时，则只会在通道 `N` 和 `C` 上做dropout，通道 `H` 和 `W` 的元素是绑定在一起的，即： ``paddle.nn.functional.dropout(x, p, axis=[0,1])`` ， 此时对4维张量中的某个2维特征图(形状 `HW` )，或者全部置0，或者全部保留，这便是dropout2d的实现。详情参考 :ref:`cn_api_nn_functional_dropout2d` 。 + +类似的，若输入x为5维张量，形状为 `NCDHW` , 当设置 ``axis=[0,1]`` 时，便可实现dropout3d。详情参考 :ref:`cn_api_nn_functional_dropout3d` 。 + +.. note:: + 关于广播(broadcasting)机制，如您想了解更多，请参见 :ref:`cn_user_guide_broadcasting` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.array([[1,2,3], [4,5,6]]).astype('float32') + x = paddle.to_tensor(x) + y_train = paddle.nn.functional.dropout(x, 0.5) + y_test = paddle.nn.functional.dropout(x, 0.5, training=False) #test + y_0 = paddle.nn.functional.dropout(x, axis=0) + y_1 = paddle.nn.functional.dropout(x, axis=1) + y_01 = paddle.nn.functional.dropout(x, axis=[0,1]) + print(x.numpy()) + print(y_train.numpy()) + print(y_test.numpy()) + print(y_0.numpy()) + print(y_1.numpy()) + print(y_01.numpy()) diff --git a/doc/paddle/api/paddle/nn/functional/common/pad_cn.rst b/doc/paddle/api/paddle/nn/functional/common/pad_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d4d7b998b550be9cf85b9c02ab2e05b6414a68fe --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/common/pad_cn.rst @@ -0,0 +1,97 @@ +.. _cn_api_nn_cn_pad: + +pad +------------------------------- + +.. py:function:: paddle.nn.functional.pad(x, pad, mode="constant", value=0.0, data_format="NCHW", name=None) + +该OP依照 pad 和 mode 属性对input进行 ``pad`` 。 + +参数： + - **x** (Tensor) - Tensor，format可以为 `'NCL'`, `'NLC'`, `'NCHW'`, `'NHWC'`, `'NCDHW'` + 或 `'NDHWC'`，默认值为`'NCHW'`，数据类型支持float16, float32, float64, int32, int64。 + - **pad** (Tensor | List[int32]) - 填充大小。当输入维度为3时，pad的格式为[pad_left, pad_right]； + 当输入维度为4时，pad的格式为[pad_left, pad_right, pad_top, pad_bottom]； + 当输入维度为5时，pad的格式为[pad_left, pad_right, pad_top, pad_bottom, pad_front, pad_back]。 + - **mode** (str) - padding的四种模式，分别为 `'constant'`, `'reflect'`, `'replicate'` 和`'circular'`。 + `'constant'` 表示填充常数 `value`；`'reflect'` 表示填充以input边界值为轴的映射；`'replicate'` 表示 + 填充input边界值；`'circular'`为循环填充input。具体结果可见以下示例。默认值为 `'constant'` 。 + - **value** (float32) - 以 `'constant'` 模式填充区域时填充的值。默认值为0.0。 + - **data_format** (str) - 指定input的format，可为 `'NCL'`, `'NLC'`, `'NCHW'`, `'NHWC'`, `'NCDHW'` + 或 `'NDHWC'`，默认值为`'NCHW'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 +返回： 对input进行``pad`` 的结果，数据类型和input相同。 + +返回类型：Tensor + +**示例**： + +.. code-block:: text + + x = [[[[[1., 2., 3.], + [4., 5., 6.]]]]] + + Case 0: + pad = [2, 2, 1, 1, 0, 0], + mode = 'constant' + pad_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.]]]]] + + Case 1: + 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.]]]]] + + Case 2: + 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.]]]]] + + Case 3: + 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.]]]]] + +**代码示例：** + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn.functional as F + + paddle.disable_static() + + # example 1 + x_shape = (1, 1, 3) + x = np.arange(np.prod(x_shape), dtype=np.float32).reshape(x_shape) + 1 + tensor_x = paddle.to_tensor(x) + y = F.pad(tensor_x, [2, 3], value=1, mode='constant') + print(y.numpy()) + # [[[1. 1. 1. 2. 3. 1. 1. 1.]]] + + # example 2 + x_shape = (1, 1, 2, 3) + x = np.arange(np.prod(x_shape), dtype=np.float32).reshape(x_shape) + 1 + tensor_x = paddle.to_tensor(x) + y = F.pad(tensor_x, [1, 2, 1, 1], value=1, mode='circular') + print(y.numpy()) + # [[[[6. 4. 5. 6. 4. 5.] + # [3. 1. 2. 3. 1. 2.] + # [6. 4. 5. 6. 4. 5.] + # [3. 1. 2. 3. 1. 2.]]]] + + + diff --git a/doc/paddle/api/paddle/nn/functional/dropout_cn.rst b/doc/paddle/api/paddle/nn/functional/dropout_cn.rst deleted file mode 100644 index 8c748ec91af6395405bb46a43b3e94b59ebfa153..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/dropout_cn.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _cn_api_fluid_layers_dropout: - -dropout -------------------------------- - -.. py:function:: paddle.fluid.layers.dropout(x,dropout_prob,is_test=False,seed=None,name=None,dropout_implementation='downgrade_in_infer') - -:alias_main: paddle.nn.functional.dropout -:alias: paddle.nn.functional.dropout,paddle.nn.functional.common.dropout -:old_api: paddle.fluid.layers.dropout - - - -dropout操作 - -丢弃或者保持x的每个元素独立。Dropout是一种正则化手段，通过在训练过程中阻止神经元节点间的相关性来减少过拟合。根据给定的丢弃概率，dropout操作符按丢弃概率随机将一些神经元输出设置为0，其他的仍保持不变。 - -dropout op可以从Program中删除，提高执行效率。 - -参数： - - **x** (Variable) - 输入，多维Tensor。数据类型：float32和float64。 - - **dropout_prob** (float32) - 输入单元的丢弃概率，即输入单元设置为0的概率。 - - **is_test** (bool) - 标记是否是测试阶段。默认：False。 - - **seed** (int) - 整型数据，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。 - - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。 - - **dropout_implementation** (str) - 丢弃单元的方式，有两种'downgrade_in_infer'和'upscale_in_train'两种选择，默认：'downgrade_in_infer'。具体作用可以参考一下描述。 - - 1. downgrade_in_infer(default), 在预测时减小输出结果 - - - train: out = input * mask - - - inference: out = input * (1.0 - dropout_prob) - - (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ) - - 2. upscale_in_train, 增加训练时的结果 - - - train: out = input * mask / ( 1.0 - dropout_prob ) - - - inference: out = input - - (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ） - -dropout操作符可以从程序中移除，使程序变得高效。 - -返回：Tensor。经过丢弃部分数据之后的结果，与输入X形状相同的张量。 - -返回类型：Variable - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - x = fluid.layers.data(name="x", shape=[32, 32], dtype="float32") - droped = fluid.layers.dropout(x, dropout_prob=0.5) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - np_x = np.random.random(size=(32, 32)).astype('float32') - output = exe.run(feed={"x": np_x}, fetch_list = [droped]) - print(output) - diff --git a/doc/paddle/api/paddle/nn/functional/elu_cn.rst b/doc/paddle/api/paddle/nn/functional/elu_cn.rst deleted file mode 100644 index 6d527ce9359d4b2561e7018b72e79839d158d8c2..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/elu_cn.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _cn_api_fluid_layers_elu: - -elu -------------------------------- - -.. py:function:: paddle.fluid.layers.elu(x, alpha=1.0, name=None) - -:alias_main: paddle.nn.functional.elu -:alias: paddle.nn.functional.elu,paddle.nn.functional.activation.elu -:old_api: paddle.fluid.layers.elu - - - -ELU激活层（ELU Activation Operator） - -根据 https://arxiv.org/abs/1511.07289 对输入Tensor中每个元素应用以下计算。 - -.. math:: - \\out=max(0,x)+min(0,α∗(e^{x}−1))\\ - -参数: - - **x** (Variable) - 该OP的输入为多维Tensor。数据类型为float32或float64。 - - **alpha** (float, 可选) - ELU的alpha值，默认值为1.0。 - - **name** (str, 可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为None。 - -返回: 输出为Tensor，与 ``x`` 维度相同、数据类型相同。 - -返回类型： Variable - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - input_elu = np.array([[-1,6],[1,15.6]]) - with fluid.dygraph.guard(): - x = fluid.dygraph.to_variable(input_elu) - y = fluid.layers.elu(x, alpha=0.2) - print(y.numpy()) - # [[-0.12642411 6. ] - # [ 1. 15.6 ]] diff --git a/doc/paddle/api/paddle/nn/functional/gelu_cn.rst b/doc/paddle/api/paddle/nn/functional/gelu_cn.rst deleted file mode 100644 index c234e3b574b2ee089f6cc39b000f28590ad1630d..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/gelu_cn.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _cn_api_fluid_layers_gelu: - -gelu -------------------------------- - -.. py:function:: paddle.fluid.layers.gelu(x) - -:alias_main: paddle.nn.functional.gelu -:alias: paddle.nn.functional.gelu,paddle.nn.functional.activation.gelu -:old_api: paddle.fluid.layers.gelu - - - -逐元素计算 Gelu激活函数。更多细节请参考 `Gaussian Error Linear Units `_ 。 - -如果使用近似计算： - -.. math:: - out = 0.5 * x * (1 + tanh(\sqrt{\frac{2}{\pi}} * (x + 0.044715x^{3}))) - -如果不使用近似计算： - -.. math:: - out = 0.5 * x * (1 + erf(\frac{x}{\sqrt{2}})) - -参数： - - **x** (Variable) - Gelu Op 的输入，多维 Tensor 或 LoDTensor，数据类型为 float32 或 float64。 - - **approximate** (bool, 可选) - 是否使用近似计算，默认值为 False。 - -返回： - - 多维 Tensor 或 LoDTensor, 数据类型为 float32 或 float64， 和输入 x 的数据类型相同，形状和输入 x 相同。 - -返回类型： - - Variable - -**代码示例**： - -.. code-block:: python - - # declarative mode - import numpy as np - from paddle import fluid - - x = fluid.data(name="x", shape=(-1, 3), dtype="float32") - y = fluid.layers.gelu(x) - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - start = fluid.default_startup_program() - main = fluid.default_main_program() - - data = np.random.randn(2, 3).astype("float32") - exe.run(start) - - y_np, = exe.run(main, feed={"x": data}, fetch_list=[y]) - - data - # array([[ 0.87165993, -1.0541513 , -0.37214822], - # [ 0.15647964, 0.32496083, 0.33045998]], dtype=float32) - y_np - # array([[ 0.70456535, -0.15380788, -0.13207214], - # [ 0.08796856, 0.20387867, 0.2080159 ]], dtype=float32) - -.. code-block:: python - - # imperative mode - import numpy as np - from paddle import fluid - import paddle.fluid.dygraph as dg - - data = np.random.randn(2, 3).astype("float32") - place = fluid.CPUPlace() - with dg.guard(place) as g: - x = dg.to_variable(data) - y = fluid.layers.gelu(x) - y_np = y.numpy() - data - # array([[ 0.87165993, -1.0541513 , -0.37214822], - # [ 0.15647964, 0.32496083, 0.33045998]], dtype=float32) - y_np - # array([[ 0.70456535, -0.15380788, -0.13207214], - # [ 0.08796856, 0.20387867, 0.2080159 ]], dtype=float32) diff --git a/doc/paddle/api/paddle/nn/functional/input/embedding_cn.rst b/doc/paddle/api/paddle/nn/functional/input/embedding_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..b5ad3607114832a799d763d7d68b05a60d65a55d --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/input/embedding_cn.rst @@ -0,0 +1,103 @@ +.. _cn_api_fluid_layers_embedding: + +embedding +------------------------------- + + +.. py:function:: paddle.fluid.layers.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') + +:api_attr: 声明式编程模式（静态图) + + + +嵌入层(Embedding Layer) + +**注意：此OP将在未来的版本中被移除！该OP要求输入Tensor shape的最后一维必须为1。推荐使用fluid.** :ref:`cn_api_fluid_embedding` 。 + +该OP根据input中的id信息从embedding矩阵中查询对应embedding信息，并会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。 + +要求input的最后一维必须等于1，输出的Tensor的shape是将输入Tensor shape的最后一维的1替换为emb_size。 + +注：input中的id必须满足 ``0 =< id < size[0]``，否则程序会抛异常退出。 + + +:: + + Case 1: + + input是Tensor, 且padding_idx = -1 + input.data = [[[1], [3]], [[2], [4]], [[4], [127]]] + input.shape = [3, 2, 1] + 若size = [128, 16] + 输出为Tensor: + out.shape = [3, 2, 16] + out.data = [[[0.129435295, 0.244512452, ..., 0.436322452], + [0.345421456, 0.524563927, ..., 0.144534654]], + + [[0.345249859, 0.124939536, ..., 0.194353745], + [0.945345345, 0.435394634, ..., 0.435345365]], + + [[0.945345345, 0.435394634, ..., 0.435345365], + [0.0, 0.0, ..., 0.0 ]]] # padding data + 输入的padding_idx小于0，则自动转换为padding_idx = -1 + 128 = 127, 对于输入id为127的词，进行padding处理。 + + Case 2: + + input是lod level 为1的LoDTensor, 且padding_idx = 0 + input.lod = [[2, 3]] + input.data = [[1], [3], [2], [4], [0]] + input.shape = [5, 1] + 若size = [128, 16] + 输出为LoDTensor: + out.lod = [[2, 3]] + out.shape = [5, 16] + out.data = [[0.129435295, 0.244512452, ..., 0.436322452], + [0.345421456, 0.524563927, ..., 0.144534654], + [0.345249859, 0.124939536, ..., 0.194353745], + [0.945345345, 0.435394634, ..., 0.435345365], + [0.0, 0.0, ..., 0.0 ]] # padding data + 输入的padding_idx = 0，则对于输入id为0的词，进行padding处理。 + + +参数： + - **input** (Variable) - 存储id信息的Tensor或LoDTensor，数据类型必须为：int64，输入的shape最后一维须为1。input中的id必须满足 ``0 =< id < size[0]`` 。 + - **size** (tuple|list) - embedding矩阵的维度。必须包含两个元素，第一个元素为vocab_size(词表大小), 第二个为emb_size（embedding层维度）。 + - **is_sparse** (bool) - 是否使用稀疏的更新方式，这个参数只会影响反向的梯度更新的性能，sparse更新速度更快，推荐使用稀疏更新的方式。但某些optimizer不支持sparse更新，比如 :ref:`cn_api_fluid_optimizer_AdadeltaOptimizer` 、 :ref:`cn_api_fluid_optimizer_AdamaxOptimizer` 、 :ref:`cn_api_fluid_optimizer_DecayedAdagradOptimizer` 、 :ref:`cn_api_fluid_optimizer_FtrlOptimizer` 、 :ref:`cn_api_fluid_optimizer_LambOptimizer` 、:ref:`cn_api_fluid_optimizer_LarsMomentumOptimizer` ，此时is_sparse必须为False。默认为False。 + - **is_distributed** (bool) - 是否使用分布式的方式存储embedding矩阵，仅在多机分布式cpu训练中使用。默认为False。 + - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx会被改成vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为None，不作处理，默认为None。 + - **param_attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为numpy数据格式，且保证本地词向量的shape和embedding的 ``size`` 参数一致，然后使用 :ref:`cn_api_fluid_initializer_NumpyArrayInitializer` 进行初始化，即可实现加载自定义或预训练的词向量。详细使用方法见代码示例2。 + - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32或float64，默认为float32。 + +返回：input映射后得到的Embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 + +返回类型：Variable + +**代码示例**: + +.. code-block:: python + + import paddle.fluid as fluid + import numpy as np + + data = fluid.layers.data(name='sequence', shape=[1], dtype='int64', lod_level=1) + + # 示例 1 + emb_1 = fluid.layers.embedding(input=data, size=[128, 64]) + + # 示例 2: 加载用户自定义或预训练的词向量 + weight_data = np.random.random(size=(128, 100)) # numpy格式的词向量数据 + w_param_attrs = fluid.ParamAttr( + name="emb_weight", + learning_rate=0.5, + initializer=fluid.initializer.NumpyArrayInitializer(weight_data), + trainable=True) + emb_2 = fluid.layers.embedding(input=data, size=(128, 100), param_attr=w_param_attrs, dtype='float32') + + + + + + + + + diff --git a/doc/paddle/api/paddle/nn/functional/input/one_hot_cn.rst b/doc/paddle/api/paddle/nn/functional/input/one_hot_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..9df99a99421004e31491c28c6223d3b0bfc3f752 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/input/one_hot_cn.rst @@ -0,0 +1,60 @@ +.. _cn_api_nn_functional_one_hot: + +one_hot +------------------------------- + +.. py:function:: paddle.nn.functional.one_hot(x, num_classes, name=None) +该OP将输入'x'中的每个id转换为一个one-hot向量，其长度为 ``num_classes`` ，该id对应的向量维度上的值为1，其余维度的值为0。 + +输出的Tensor的shape是在输入shape的最后一维后面添加了num_classes的维度。 + +- 示例1： + +.. code-block:: text + + 输入： + X.shape = [4] + X.data = [1, 1, 3, 0] + num_classes = 4 + + 输出： + Out.shape = [4, 4] + Out.data = [[0., 1., 0., 0.], + [0., 1., 0., 0.], + [0., 0., 0., 1.], + [1., 0., 0., 0.]] + +- 示例2： + +.. code-block:: text + + 输入： + X.shape = [4] + X.data = [1, 1, 5, 0] + num_classes = 4 + + 输出：抛出 Illegal value 的异常 + X中第2维的值是5，超过了num_classes，因此抛异常。 + + +参数： + - **x** (Tensor) - 维度为 :math:`[N_1, ..., N_n]` 的多维Tensor，维度至少1维。数据类型为int32或int64。 + - **num_classes** (int) - 用于定义一个one-hot向量的长度。若输入为词id，则 ``num_classes`` 通常取值为词典大小。 + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：Tensor，转换后的one_hot Tensor，数据类型为float32。 + +**代码示例**： + +.. code-block:: python + + import paddle + label = paddle.data(name="label", shape=[4], dtype="int64") + # label.shape = [4] + # label.data = [1, 1, 3, 0] + one_hot_label = paddle.nn.functional.one_hot(x=label, num_classes=4) + # one_hot_label.shape = [4, 4] + # one_hot_label.data = [[0., 1., 0., 0.], + # [0., 1., 0., 0.], + # [0., 0., 0., 1.], + # [1., 0., 0., 0.]] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/functional/leaky_relu_cn.rst b/doc/paddle/api/paddle/nn/functional/leaky_relu_cn.rst deleted file mode 100644 index 736a39e0dfded848089f7511031addc5cf71dfe4..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/leaky_relu_cn.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _cn_api_fluid_layers_leaky_relu: - -leaky_relu -------------------------------- - -.. py:function:: paddle.fluid.layers.leaky_relu(x, alpha=0.02, name=None) - -:alias_main: paddle.nn.functional.leaky_relu -:alias: paddle.nn.functional.leaky_relu,paddle.nn.functional.activation.leaky_relu -:old_api: paddle.fluid.layers.leaky_relu - - - -LeakyRelu激活函数 - -.. math:: out=max(x,α∗x) - -参数: - - **x** (Variable) - 输入的多维LoDTensor/Tensor，数据类型为：float32，float64。 - - **alpha** (float) - 负斜率，缺省值为0.02。 - - **name** (str，可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 - -返回: 与 ``x`` 维度相同，数据类型相同的LodTensor/Tensor。 - -返回类型: Variable - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # Graph Organizing - x = fluid.layers.data(name="x", shape=[2], dtype="float32") - res = fluid.layers.leaky_relu(x, alpha=0.1) - - # Create an executor using CPU as an example - exe = fluid.Executor(fluid.CPUPlace()) - exe.run(fluid.default_startup_program()) - - # Execute - x_i = np.array([[-1, 2], [3, -4]]).astype(np.float32) - res_val, = exe.run(fluid.default_main_program(), feed={'x':x_i}, fetch_list=[res]) - print(res_val) # [[-0.1, 2], [3, -0.4]] - - diff --git a/doc/paddle/api/paddle/nn/functional/logsigmoid_cn.rst b/doc/paddle/api/paddle/nn/functional/logsigmoid_cn.rst deleted file mode 100644 index 94ba6048566ebe86ee6de81466bef0b5dac0d8d8..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/logsigmoid_cn.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _cn_api_fluid_layers_logsigmoid: - -logsigmoid -------------------------------- - -.. py:function:: paddle.fluid.layers.logsigmoid(x, name=None) - -:alias_main: paddle.nn.functional.logsigmoid -:alias: paddle.nn.functional.logsigmoid,paddle.nn.functional.activation.logsigmoid -:old_api: paddle.fluid.layers.logsigmoid - - - -Logsigmoid激活函数 - - -.. math:: - - out = \log \frac{1}{1 + e^{-x}} - - -参数: - - **x** (Variable)- 张量（Tensor） - - **name** (str|None) - 该层名称（可选），若设为None，则自动为该层命名。 - -返回: 张量(Tensor) - -返回类型: 变量(Variable) - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.logsigmoid(data) - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/loss/binary_cross_entropy_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/binary_cross_entropy_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..11f77916759816ce1ddb451263e3bb42106ee49a --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/binary_cross_entropy_cn.rst @@ -0,0 +1,61 @@ +.. _cn_api_nn_functional_binary_cross_entropy: + +binary_cross_entropy +------------------------------- + +.. py:functional:: paddle.nn.functional.binary_cross_entropy(input, label, weight=None, reduction='mean', name=None) + +该函数用于计算输入 ``input`` 和标签 ``label`` 之间的二值交叉熵损失值。二值交叉熵损失函数公式如下： + +当 `weight` 不为空时，公式为： + +.. math:: + Out = -1 * weight * (label * log(input) + (1 - label) * log(1 - input)) + +当 `weight` 为空时，公式为： + +.. math:: + Out = -1 * (label * log(input) + (1 - label) * log(1 - input)) + +当 `reduction` 为 `none` 时，直接返回最原始的 `Out` 结果。 + +当 `reduction` 为 `mean` 时，最终的输出结果为： + +.. math:: + Out = MEAN(Out) + +当 `reduction` 为 `sum` 时，最终的输出结果为： + +.. math:: + Out = SUM(Out) + + +.. note:: + 输入数据 ``input`` 一般是 ``sigmoid`` 的输出。因为是二分类，所以标签值 ``label`` 应该是0或者1。 + +参数 +::::::::: + - **input** (Tensor) - :math:`[N, *]` , 其中N是batch_size， `*` 是任意其他维度。输入数据 ``input`` 一般是 ``sigmoid`` 的输出。数据类型是float32、float64。 + - **label** (Tensor) - :math:`[N, *]` ，标签 ``label`` 的维度、数据类型与输入 ``input`` 相同。 + - **weight** (Tensor，可选) - 手动指定每个batch二值交叉熵的权重，如果指定的话，维度必须是一个batch的数据的维度。数据类型是float32, float64。默认值是：None。 + - **reduction** (str，可选) - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `BCELoss` 的均值；设置为 ``'sum'`` 时，计算 `BCELoss` 的总和；设置为 ``'none'`` 时，则返回bce_loss。 + - **name** (str，可选) - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: + - 输出的结果Tensor。如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 :math:`[N, *]` , 与输入 ``input`` 的形状相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 :math:`[1]` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + + paddle.disable_static() + input = paddle.to_tensor([0.5, 0.6, 0.7], dtype='float32') + label = paddle.to_tensor([1.0, 0.0, 1.0], dtype='float32') + output = F.binary_cross_entropy(input, label) + print(output.numpy()) # [0.65537095] + diff --git a/doc/paddle/api/paddle/nn/functional/loss/binary_cross_entropy_with_logits_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/binary_cross_entropy_with_logits_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..18279319b1c0c6f9568e0af6e93bf52bb4cf0b22 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/binary_cross_entropy_with_logits_cn.rst @@ -0,0 +1,59 @@ +.. _cn_api_paddle_nn_functional_binary_cross_entropy_with_logits: + +binary_cross_entropy_with_logits +------------------------------- + +.. py:function:: paddle.nn.functional.binary_cross_entropy_with_logits(logit, label, weight=None, reduction='mean', pos_weight=None, name=None) + +该OP用于计算输入 `logit` 和标签 `label` 间的 `binary cross entropy with logits loss` 损失。 + +该OP结合了 `sigmoid` 操作和 :ref:`api_nn_loss_BCELoss` 操作。同时，我们也可以认为该OP是 ``sigmoid_cross_entrop_with_logits`` 和一些 `reduce` 操作的组合。 + +在每个类别独立的分类任务中，该OP可以计算按元素的概率误差。可以将其视为预测数据点的标签，其中标签不是互斥的。例如，一篇新闻文章可以同时关于政治，科技，体育或者同时不包含这些内容。 + +首先，该OP可通过下式计算损失函数： + +.. math:: + Out = -Labels * \log(\sigma(Logit)) - (1 - Labels) * \log(1 - \sigma(Logit)) + +其中 :math:`\sigma(Logit) = \frac{1}{1 + e^{-Logit}}` ， 代入上方计算公式中: + +.. math:: + Out = Logit - Logit * Labels + \log(1 + e^{-Logit}) + +为了计算稳定性，防止当 :math:`Logit<0` 时， :math:`e^{-Logit}` 溢出，loss将采用以下公式计算: + +.. math:: + Out = \max(Logit, 0) - Logit * Labels + \log(1 + e^{-\|Logit\|}) + +然后，当 ``weight`` or ``pos_weight`` 不为None的时候，该算子会在输出Out上乘以相应的权重。张量 ``weight`` 给Batch中的每一条数据赋予不同权重，张量 ``pos_weight`` 给每一类的正例添加相应的权重。 + +最后，该算子会添加 `reduce` 操作到前面的输出Out上。当 `reduction` 为 `none` 时，直接返回最原始的 `Out` 结果。当 `reduction` 为 `mean` 时，返回输出的均值 :math:`Out = MEAN(Out)` 。当 `reduction` 为 `sum` 时，返回输出的求和 :math:`Out = SUM(Out)` 。 + +**注意: 因为是二分类任务，所以标签值应该是0或者1。 + +参数 +::::::::: + - **logit** (Tensor) - :math:`[N, *]` , 其中N是batch_size， `*` 是任意其他维度。输入数据 ``logit`` 一般是线性层的输出，不需要经过 ``sigmoid`` 层。数据类型是float32、float64。 + - **label** (Tensor) - :math:`[N, *]` ，标签 ``label`` 的维度、数据类型与输入 ``logit`` 相同。 + - **weight** (Tensor，可选) - 手动指定每个batch二值交叉熵的权重，如果指定的话，维度必须是一个batch的数据的维度。数据类型是float32, float64。默认值是：None。 + - **reduction** (str，可选) - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `BCELoss` 的均值；设置为 ``'sum'`` 时，计算 `BCELoss` 的总和；设置为 ``'none'`` 时，则返回原始loss。 + - **pos_weight** (Tensor，可选) - 手动指定正类的权重，必须是与类别数相等长度的向量。数据类型是float32, float64。默认值是：None。 + - **name** (str，可选) - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: + - Tensor，输出的Tensor。如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 :math:`[N, *]` , 与输入 ``input`` 的形状相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 :math:`[1]` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + paddle.disable_static() + logit = paddle.to_tensor([5.0, 1.0, 3.0], dtype="float32") + label = paddle.to_tensor([1.0, 0.0, 1.0], dtype="float32") + output = paddle.nn.functional.binary_cross_entropy_with_logits(logit, label) + print(output.numpy()) # [0.45618808] + diff --git a/doc/paddle/api/paddle/nn/functional/cross_entropy_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/cross_entropy_cn.rst similarity index 100% rename from doc/paddle/api/paddle/nn/functional/cross_entropy_cn.rst rename to doc/paddle/api/paddle/nn/functional/loss/cross_entropy_cn.rst diff --git a/doc/paddle/api/paddle/nn/functional/loss/ctc_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/ctc_loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..2722525a61feefc4ea1bb3263e7eec0f88462796 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/ctc_loss_cn.rst @@ -0,0 +1,80 @@ +ctc_loss +------------------------------- + +.. py:function:: paddle.nn.functional.ctc_loss(log_probs, labels, input_lengths, label_lengths, blank=0, reduction='mean') + +该接口用于计算 CTC loss。该接口的底层调用了第三方 baidu-research::warp-ctc 的实现。 +也可以叫做 softmax with CTC，因为 Warp-CTC 库中插入了 softmax 激活函数来对输入的值进行归一化。 + +参数 +::::::::: + - **log_probs** (Tensor): - 经过 padding 的概率序列，其 shape 必须是 [max_logit_length, batch_size, num_classes + 1]。其中 max_logit_length 是最长输入序列的长度。该输入不需要经过 softmax 操作，因为该 OP 的内部对 input 做了 softmax 操作。数据类型仅支持float32。 + - **labels** (Tensor): - 经过 padding 的标签序列，其 shape 为 [batch_size, max_label_length]，其中 max_label_length 是最长的 label 序列的长度。数据类型支持int32。 + - **input_lengths** (Tensor): - 表示输入 ``log_probs`` 数据中每个序列的长度，shape为 [batch_size] 。数据类型支持int64。 + - **label_lengths** (Tensor): - 表示 label 中每个序列的长度，shape为 [batch_size] 。数据类型支持int64。 + - **blank** (int，可选): - 空格标记的 ID 值，其取值范围为 [0，num_classes+1) 。数据类型支持int32。默认值为0。 + - **reduction** (string，可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'``。设置为 ``'mean'`` 时，对 loss 值除以 label_lengths，并返回所得商的均值；设置为 ``'sum'`` 时，返回 loss 值的总和；设置为 ``'none'`` 时，则直接返回输出的 loss 值。默认值为 ``'mean'``。 + +返回 +::::::::: +``Tensor``，输入 ``log_probs`` 和标签 ``labels`` 间的 `ctc loss`。如果 :attr:`reduction` 是 ``'none'``, 则输出 loss 的维度为 [batch_size]。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``，则输出Loss的维度为 [1]。数据类型与输入 ``log_probs`` 一致。 + + +代码示例 +::::::::: + +.. code-block:: python + + # declarative mode + import paddle.nn.functional as F + import numpy as np + import paddle + + # length of the longest logit sequence + max_seq_length = 4 + #length of the longest label sequence + max_label_length = 3 + # number of logit sequences + batch_size = 2 + # class num + class_num = 3 + + np.random.seed(1) + log_probs = np.array([[[4.17021990e-01, 7.20324516e-01, 1.14374816e-04], + [3.02332580e-01, 1.46755889e-01, 9.23385918e-02]], + + [[1.86260208e-01, 3.45560730e-01, 3.96767467e-01], + [5.38816750e-01, 4.19194520e-01, 6.85219526e-01]], + + [[2.04452246e-01, 8.78117442e-01, 2.73875929e-02], + [6.70467496e-01, 4.17304814e-01, 5.58689833e-01]], + + [[1.40386939e-01, 1.98101491e-01, 8.00744593e-01], + [9.68261600e-01, 3.13424170e-01, 6.92322612e-01]], + + [[8.76389146e-01, 8.94606650e-01, 8.50442126e-02], + [3.90547849e-02, 1.69830427e-01, 8.78142476e-01]]]).astype("float32") + labels = np.array([[1, 2, 2], + [1, 2, 2]]).astype("int32") + input_lengths = np.array([5, 5]).astype("int64") + label_lengths = np.array([3, 3]).astype("int64") + + paddle.disable_static() + log_probs = paddle.to_tensor(log_probs) + labels = paddle.to_tensor(labels) + input_lengths = paddle.to_tensor(input_lengths) + label_lengths = paddle.to_tensor(label_lengths) + + loss = F.ctc_loss(log_probs, labels, + input_lengths, + label_lengths, + blank=0, + reduction='none') + print(loss.numpy()) #[3.9179852 2.9076521] + + loss = F.ctc_loss(log_probs, labels, + input_lengths, + label_lengths, + blank=0, + reduction='mean') + print(loss.numpy()) #[1.1376063] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/functional/loss/l1_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/l1_loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..77c9a232a61d8f922a3cfd70c3e95508249f199b --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/l1_loss_cn.rst @@ -0,0 +1,63 @@ +l1_loss +------------------------------- + +.. py:function:: paddle.nn.functional.l1_loss(input, label, reduction='mean', name=None) + +该接口计算输入 ``input`` 和标签 ``label`` 间的 `L1 loss` 损失。 + +该损失函数的数学计算公式如下： + +当 `reduction` 设置为 ``'none'`` 时， + + .. math:: + Out = \lvert input - label\rvert + +当 `reduction` 设置为 ``'mean'`` 时， + + .. math:: + Out = MEAN(\lvert input - label\rvert) + +当 `reduction` 设置为 ``'sum'`` 时， + + .. math:: + Out = SUM(\lvert input - label\rvert) + + +参数 +::::::::: + - **input** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64、int32、int64。 + - **label** (Tensor): - 标签，维度是[N, *], 与 ``input`` 相同。数据类型为：float32、float64、int32、int64。 + - **reduction** (str, 可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `L1Loss` 的均值；设置为 ``'sum'`` 时，计算 `L1Loss` 的总和；设置为 ``'none'`` 时，则返回 `L1Loss`。 + - **name** (str，可选): - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +::::::::: +``Tensor``, 输入 ``input`` 和标签 ``label`` 间的 `L1 loss` 损失。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``input`` 相同。如果 `reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 + + +代码示例 +::::::::: + +.. code-block:: python + + import numpy as np + import paddle + + paddle.disable_static() + input_data = np.array([[1.5, 0.8], [0.2, 1.3]]).astype("float32") + label_data = np.array([[1.7, 1], [0.4, 0.5]]).astype("float32") + input = paddle.to_variable(input_data) + label = paddle.to_variable(label_data) + + l1_loss = paddle.nn.functional.l1_loss(input, label) + print(l1_loss.numpy()) + # [0.35] + + l1_loss = paddle.nn.functional.l1_loss(input, label, reduction='none') + print(l1_loss.numpy()) + # [[0.20000005 0.19999999] + # [0.2 0.79999995]] + + l1_loss = paddle.nn.functional.l1_loss(input, label, reduction='sum') + print(l1_loss.numpy()) + # [1.4] diff --git a/doc/paddle/api/paddle/nn/functional/loss/margin_ranking_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/margin_ranking_loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..edc1d7c7d1ffe659255e1f92a6a43e0d78af1bcf --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/margin_ranking_loss_cn.rst @@ -0,0 +1,52 @@ +.. _cn_api_nn_cn_margin_ranking_loss: + +margin_ranking_loss +------------------------------- + +.. py:function:: paddle.nn.functional.margin_ranking_loss(input, other, label, margin=0.0, reduction='mean', name=None) + +该算子计算输入input，other 和 标签label间的 `margin rank loss` 损失。该损失函数的数学计算公式如下： + + .. math:: + margin\_rank\_loss = max(0, -label * (input - other) + margin) + +当 `reduction` 设置为 ``'mean'`` 时， + + .. math:: + Out = MEAN(margin\_rank\_loss) + +当 `reduction` 设置为 ``'sum'`` 时， + + .. math:: + Out = SUM(margin\_rank\_loss) + +当 `reduction` 设置为 ``'none'`` 时，直接返回最原始的 `margin_rank_loss` 。 + +参数 +:::::::: + - **input** （Tensor）：第一个输入的 `Tensor` ，数据类型为：float32、float64。 + - **other** （Tensor）：第二个输入的 `Tensor` ，数据类型为：float32、float64。 + - **label** （Tensor）：训练数据的标签，数据类型为：float32, float64。 + - **margin** （float，可选）： - 用于加和的margin值，默认值为0。 + - **reduction** （string，可选）： - 指定应用于输出结果的计算方式，可选值有: ``'none'`` 、 ``'mean'`` 、 ``'sum'`` 。如果设置为 ``'none'`` ，则直接返回 最原始的 ``margin_rank_loss`` 。如果设置为 ``'sum'`` ，则返回 ``margin_rank_loss`` 的总和。如果设置为 ``'mean'`` ，则返回 ``margin_rank_loss`` 的平均值。默认值为 ``'none'`` 。 + - **name** （str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +:::::::: +Tensor, 如果 :attr:`reduction` 为 ``'sum'`` 或者是 ``'mean'`` ，则形状为 :math:`[1]` ，否则shape和输入 `input` 保持一致 。数据类型与 ``input``、 ``other`` 相同。 + +代码示例 +:::::::: + +.. code-block:: python + + import numpy as np + import paddle + + paddle.disable_static() + + input = paddle.to_variable(np.array([[1, 2], [3, 4]]).astype('float32')) + other = paddle.to_variable(np.array([[2, 1], [2, 4]]).astype('float32')) + label = paddle.to_variable(np.array([[1, -1], [-1, -1]]).astype('float32')) + loss = paddle.nn.functional.margin_ranking_loss(input, other, label) + print(loss.numpy()) # [0.75] diff --git a/doc/paddle/api/paddle/nn/functional/loss/mse_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/mse_loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..99041e8ac0bf5c0f5558c096d6e152b8b62b9094 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/mse_loss_cn.rst @@ -0,0 +1,66 @@ +mse_loss +------------------------------- + +.. py:function:: paddle.nn.functional.mse_loss(input, label, reduction='mean', name=None) + +该OP用于计算预测值和目标值的均方差误差。 + +对于预测值input和目标值label，公式为： + +当 `reduction` 设置为 ``'none'`` 时， + + .. math:: + Out = (input - label)^2 + +当 `reduction` 设置为 ``'mean'`` 时， + + .. math:: + Out = \operatorname{mean}((input - label)^2) + +当 `reduction` 设置为 ``'sum'`` 时， + + .. math:: + Out = \operatorname{sum}((input - label)^2) + + +参数： +::::::::: + - **input** (Tensor) - 预测值，维度为 :math:`[N_1, N_2, ..., N_k]` 的多维Tensor。数据类型为float32或float64。 + - **label** (Tensor) - 目标值，维度为 :math:`[N_1, N_2, ..., N_k]` 的多维Tensor。数据类型为float32或float64。 + +返回 +::::::::: +``Tensor``, 输入 ``input`` 和标签 ``label`` 间的 `mse loss` 损失。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + # static graph mode + paddle.enable_static() + mse_loss = paddle.nn.loss.MSELoss() + input = paddle.data(name="input", shape=[1]) + label = paddle.data(name="label", shape=[1]) + place = paddle.CPUPlace() + input_data = np.array([1.5]).astype("float32") + label_data = np.array([1.7]).astype("float32") + output = mse_loss(input,label) + exe = paddle.static.Executor(place) + exe.run(paddle.static.default_startup_program()) + output_data = exe.run( + paddle.static.default_main_program(), + feed={"input":input_data, "label":label_data}, + fetch_list=[output], + return_numpy=True) + print(output_data) + # [array([0.04000002], dtype=float32)] + # dynamic graph mode + paddle.disable_static() + input = paddle.to_variable(input_data) + label = paddle.to_variable(label_data) + output = mse_loss(input, label) + print(output.numpy()) + # [0.04000002] + diff --git a/doc/paddle/api/paddle/nn/functional/loss/nll_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/nll_loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..59a1c6355e304b7ac6d9dca44031408bda008f78 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/nll_loss_cn.rst @@ -0,0 +1,45 @@ +.. _cn_api_nn_functional_nll_loss: + +nll_loss +------------------------------- +.. py:function:: paddle.nn.functional.nll_loss(input, label, weight=None, ignore_index=-100, reduction='mean', name=None) + +该接口返回 `negative log likelihood` 。可在 :ref:`cn_api_nn_loss_NLLLoss` 查看详情。 + +参数 +::::::::: + - **input** (Tensor): - 输入 `Tensor`, 其形状为 :math:`[N, C]` , 其中 `C` 为类别数。但是对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_K]` 。数据类型为float32或float64。 + - **label** (Tensor): - 输入x对应的标签值。其形状为 :math:`[N,]` 或者 :math:`[N, d_1, d_2, ..., d_K]`, 数据类型为int64。 + - **weight** (Tensor, 可选): - 手动指定每个类别的权重。其默认为 `None` 。如果提供该参数的话，长度必须为 `num_classes` 。数据类型为float32或float64。 + - **ignore_index** (int64, 可选): - 指定一个忽略的标签值，此标签值不参与计算。默认值为-100。数据类型为int64。 + - **reduction** (str, 可选): - 指定应用于输出结果的计算方式，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算 `mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。数据类型为string。 + - **name** (str, 可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +`Tensor` ，返回存储表示 `negative log likelihood loss` 的损失值。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + from paddle.nn.functional import nll_loss + log_softmax = paddle.nn.LogSoftmax(axis=1) + + input_np = np.array([[0.88103855, 0.9908683 , 0.6226845 ], + [0.53331435, 0.07999352, 0.8549948 ], + [0.25879037, 0.39530203, 0.698465 ], + [0.73427284, 0.63575995, 0.18827209], + [0.05689114, 0.0862954 , 0.6325046 ]]).astype(np.float32) + label_np = np.array([0, 2, 1, 1, 0]).astype(np.int64) + + place = paddle.CPUPlace() + paddle.disable_static(place) + input = paddle.to_variable(input_np) + log_out = log_softmax(input) + label = paddle.to_variable(label_np) + result = nll_loss(log_out, label) + print(result.numpy()) # [1.0720209] diff --git a/doc/paddle/api/paddle/nn/functional/loss/smooth_l1_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/loss/smooth_l1_loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..50e419b69b7e9d55ff26b5668b3de02e7b098128 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/loss/smooth_l1_loss_cn.rst @@ -0,0 +1,48 @@ +smooth_l1_loss +------------------------------- + +.. py:function:: paddle.nn.functional.smooth_l1_loss(input, label, reduction='mean', delta=1.0, name=None) + +该OP计算输入input和标签label间的SmoothL1损失，如果逐个元素的绝对误差低于1，则创建使用平方项的条件 +，否则为L1损失。在某些情况下，它可以防止爆炸梯度, 也称为Huber损失,该损失函数的数学计算公式如下： + + .. math:: + loss(x,y)=\\frac{1}{n}\\sum_{i}z_i + +`z_i`的计算公式如下： + + .. math:: + + \\mathop{z_i}=\\left\\{\\begin{array}{rcl} + 0.5(x_i - y_i)^2 & & {if |x_i - y_i| < delta} \\\\ + delta * |x_i - y_i| - 0.5 * delta^2 & & {otherwise} + \\end{array} \\right. + +参数 +:::::::::: + - **input** (Tensor): 输入 `Tensor`， 数据类型为float32。其形状为 :math:`[N, C]` , 其中 `C` 为类别数。对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_k]`，k >= 1。 + - **label** (Tensor): 输入input对应的标签值，数据类型为float32。数据类型和input相同。 + - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，数据类型为string，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算`mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。 + - **delta** (string, 可选): SmoothL1Loss损失的阈值参数，用于控制Huber损失对线性误差或平方误差的侧重。数据类型为float32。 默认值= 1.0。 + - **name** （string，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + + +返回：返回计算 `smooth_l1_loss` 后的损失值。 + +返回类型：Tensor + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + input = np.random.rand(3,3).astype("float32") + label = np.random.rand(3,3).astype("float32") + input = paddle.to_tensor(input_data) + label = paddle.to_tensor(label_data) + output = paddle.nn.functioanl.smooth_l1_loss(input,label) + print(output.numpy()) diff --git a/doc/paddle/api/paddle/nn/functional/mse_loss_cn.rst b/doc/paddle/api/paddle/nn/functional/mse_loss_cn.rst deleted file mode 100644 index 59678570f9e91da8e2ad46212955ea0802f8a462..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/mse_loss_cn.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _cn_api_fluid_layers_mse_loss: - -mse_loss -------------------------------- - -.. py:function:: paddle.fluid.layers.mse_loss(input,label) - -:alias_main: paddle.nn.functional.mse_loss -:alias: paddle.nn.functional.mse_loss,paddle.nn.functional.loss.mse_loss -:old_api: paddle.fluid.layers.mse_loss - - - -该OP用于计算预测值和目标值的均方差误差。 - -对于预测值input和目标值label，公式为： - -.. math:: - - Out = MEAN((input-label)^{2}) - -参数： - - **input** (Variable) - 预测值，维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。 - - **label** (Variable) - 目标值，维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。 - -返回：预测值和目标值的均方差 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - y = fluid.data(name='y', shape=[1], dtype='float32') - y_predict = fluid.data(name='y_predict', shape=[1], dtype='float32') - cost = fluid.layers.mse_loss(input=y_predict, label=y) - - - diff --git a/doc/paddle/api/paddle/nn/functional/norm/batch_norm_cn.rst b/doc/paddle/api/paddle/nn/functional/norm/batch_norm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e9fee412f3a8fa00a8197f8be3502d0a9206eafc --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/norm/batch_norm_cn.rst @@ -0,0 +1,47 @@ +.. _cn_api_nn_functional_batch_norm: + +batch_norm +------------------------------- + +.. py:class:: paddle.nn.functional.batch_norm(x, running_mean, running_var, weight, bias, training=False, momentum=0.9, epsilon=1e-05, data_format='NCHW', name=None): + +推荐使用nn.BatchNorm1d，nn.BatchNorm2d, nn.BatchNorm3d，由内部调用此方法。 + +详情见 :ref:`cn_api_nn_BatchNorm1d` 。 + +参数： + - **x** (int) - 输入，数据类型为float32, float64。 + - **running_mean** (Tensor) - 均值的Tensor。 + - **running_var** (Tensor) - 方差的Tensor。 + - **weight** (Tensor) - 权重的Tensor。 + - **bias** (Tensor) - 偏置的Tensor。 + - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为“NC", "NCL", "NCHW" 或者"NCDHW"。默认值："NCHW"。 + - **name** (string, 可选) – BatchNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + + +返回：无 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.random.seed(123) + x = np.random.random(size=(2, 1, 2, 3)).astype('float32') + running_mean = np.random.random(size=1).astype('float32') + running_variance = np.random.random(size=1).astype('float32') + weight_data = np.random.random(size=1).astype('float32') + bias_data = np.random.random(size=1).astype('float32') + x = paddle.to_tensor(x) + rm = paddle.to_tensor(running_mean) + rv = paddle.to_tensor(running_variance) + w = paddle.to_tensor(weight_data) + b = paddle.to_tensor(bias_data) + batch_norm_out = paddle.nn.functional.batch_norm(x, rm, rv, w, b) + print(batch_norm_out.numpy()) diff --git a/doc/paddle/api/paddle/nn/functional/norm/instance_norm_cn.rst b/doc/paddle/api/paddle/nn/functional/norm/instance_norm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..97a49237f9605b595464027b8e137408fd645483 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/norm/instance_norm_cn.rst @@ -0,0 +1,47 @@ +.. cn_api_nn_functional_instance_norm: + +instance_norm +------------------------------- + +.. py:class:: paddle.nn.functional.instance_norm(x, running_mean, running_var, weight, bias, training=False, epsilon=1e-05, momentum=0.9, use_input_stats=True, data_format='NCHW', name=None): + +推荐使用nn.InstanceNorm1d，nn.InstanceNorm2d, nn.InstanceNorm3d，由内部调用此方法。 + +详情见 :ref:`cn_api_nn_InstanceNorm1d` 。 + +参数： + - **x** (int) - 输入，数据类型为float32, float64。 + - **running_mean** (Tensor) - 均值的Tensor。 + - **running_var** (Tensor) - 方差的Tensor。 + - **weight** (Tensor) - 权重的Tensor。 + - **bias** (Tensor) - 偏置的Tensor。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **use_input_stats** (bool, 可选) - 默认是True. + - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为“NC", "NCL", "NCHW" 或者"NCDHW"。默认值："NCHW"。 + - **name** (string, 可选) – InstanceNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + +返回：无 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.random.seed(123) + x = np.random.random(size=(2, 1, 2, 3)).astype('float32') + running_mean = np.random.random(size=1).astype('float32') + running_variance = np.random.random(size=1).astype('float32') + weight_data = np.random.random(size=1).astype('float32') + bias_data = np.random.random(size=1).astype('float32') + x = paddle.to_tensor(x) + rm = paddle.to_tensor(running_mean) + rv = paddle.to_tensor(running_variance) + w = paddle.to_tensor(weight_data) + b = paddle.to_tensor(bias_data) + instance_norm_out = paddle.nn.functional.instance_norm(x, rm, rv, w, b) + print(instance_norm_out.numpy()) diff --git a/doc/paddle/api/paddle/nn/functional/norm/layer_norm_cn.rst b/doc/paddle/api/paddle/nn/functional/norm/layer_norm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e91822acf6299380ab132fe7d945ac3fc3875487 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/norm/layer_norm_cn.rst @@ -0,0 +1,37 @@ +.. _cn_api_nn_functional_layer_norm: + +layer_norm +------------------------------- + +.. py:class:: paddle.nn.functional.layer_norm(x, normalized_shape, weight=None, bias=None, epsilon=1e-05, name=None): + +推荐使用nn.LayerNorm。 + +详情见 :ref:`cn_api_nn_LayerNorm` . + +参数： + - **x** (int) - 输入，数据类型为float32, float64。 + - **normalized_shape** (int|list|tuple) - 期望的输入是 :math:`[*, normalized_shape[0], normalized_shape[1], ..., normalized_shape[-1]]` ,如果是一个整数，会作用在最后一个维度。 + - **weight** (Tensor) - 权重的Tensor, 默认为None。 + - **bias** (Tensor) - 偏置的Tensor, 默认为None。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **name** (string, 可选) – LayerNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np.random.seed(123) + x_data = np.random.random(size=(2, 2, 2, 3)).astype('float32') + x = paddle.to_tensor(x_data) + layer_norm_out = paddle.nn.functional.layer_norm(x, x.shape[1:]) + + print(layer_norm_out.numpy()) + diff --git a/doc/paddle/api/paddle/nn/functional/norm/normalize_cn.rst b/doc/paddle/api/paddle/nn/functional/norm/normalize_cn.rst index 5c96529efb56a1cb40e6288d4409c8dac47c4b2b..04b5b185be37be17039652abf3e7c854b925d644 100644 --- a/doc/paddle/api/paddle/nn/functional/norm/normalize_cn.rst +++ b/doc/paddle/api/paddle/nn/functional/norm/normalize_cn.rst @@ -18,9 +18,9 @@ normalize 参数 ::::::::: - **x** (Tensor) - 输入可以是N-D Tensor。数据类型为：float32、float64。 - - **p** (float|int, 可选) - 范数公式中的指数值。默认值为2 - - **axis** (int, 可选）- 要进行归一化的轴。如果 `axis < 0`，轴为 `x.ndim + axis`。-1表示最后一维。默认值为1 - - **epsilon** (float，可选) - 添加到分母上的值以防止分母除0。默认值为1e-12 + - **p** (float|int, 可选) - 范数公式中的指数值。默认值:2 + - **axis** (int, 可选）- 要进行归一化的轴。如果 ``x`` 是1-D Tensor，轴固定为0。如果 `axis < 0`，轴为 `x.ndim + axis`。-1表示最后一维。 + - **epsilon** (float，可选) - 添加到分母上的值以防止分母除0。默认值为1e-12。 - **name** (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 返回 diff --git a/doc/paddle/api/paddle/nn/functional/one_hot_cn.rst b/doc/paddle/api/paddle/nn/functional/one_hot_cn.rst deleted file mode 100644 index fbf08df2176015fbe1a50ffef5da07e2a958089c..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/one_hot_cn.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _cn_api_fluid_one_hot: - -one_hot -------------------------------- - -.. py:function:: paddle.fluid.one_hot(input, depth, allow_out_of_range=False) - -:alias_main: paddle.nn.functional.one_hot -:alias: paddle.nn.functional.one_hot,paddle.nn.functional.common.one_hot -:old_api: paddle.fluid.one_hot - - - -该OP将输入（input）中的每个id转换为一个one-hot向量，其长度为 ``depth`` ，该id对应的向量维度上的值为1，其余维度的值为0。 - -输出的Tensor（或LoDTensor）的shape是在输入shape的最后一维后面添加了depth的维度。 - -- 示例1（allow_out_of_range=False）： - -.. code-block:: python - - 输入： - X.shape = [4] - X.data = [1, 1, 3, 0] - depth = 4 - - 输出： - Out.shape = [4, 4] - Out.data = [[0., 1., 0., 0.], - [0., 1., 0., 0.], - [0., 0., 0., 1.], - [1., 0., 0., 0.]] - -- 示例2 （allow_out_of_range=True）： - -.. code-block:: python - - 输入： - X.shape = [4] - X.data = [1, 1, 5, 0] - depth = 4 - allow_out_of_range=True - - 输出： - Out.shape = [4, 4] - Out.data = [[0., 1., 0., 0.], - [0., 1., 0., 0.], - [0., 0., 0., 0.], ## 这一维的值是5，超过了depth，因此填成0 - [1., 0., 0., 0.]] - -- 示例3 （allow_out_of_range=False）： - -.. code-block:: python - - 输入： - X.shape = [4] - X.data = [1, 1, 5, 0] - depth = 4 - allow_out_of_range=False - - 输出：抛出 Illegal value 的异常 - X中第2维的值是5，超过了depth，而allow_out_of_range=False表示不允许超过，因此抛异常。 - - -参数： - - **input** (Variable) - 维度为 :math:`[N_1, ..., N_n]` 的多维Tensor或LoDTensor，维度至少1维。数据类型为int32或int64。 - - **depth** (int) - 用于定义一个one-hot向量的长度。若输入为词id，则 ``depth`` 通常取值为词典大小。 - - **allow_out_of_range** (bool) - 指明input中所包含的id值是否可以大于depth值。当超过depth时，如果 `allow_out_of_range` 为False，则会抛出 `Illegal value` 的异常；如果设置为True，该id对应的向量为0向量。默认值为False。 - -返回：转换后的one_hot Tensor或LoDTensor，数据类型为float32。 - -返回类型：Variable - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - # 该代码对应上述第一个示例，其中输入label的shape是[4]，输出one_hot_label的shape是[4, 4] - label = fluid.layers.data(name="label", shape=[4], append_batch_size=False, dtype="int64") - one_hot_label = fluid.one_hot(input=label, depth=4) diff --git a/doc/paddle/api/paddle/nn/functional/pad_cn.rst b/doc/paddle/api/paddle/nn/functional/pad_cn.rst deleted file mode 100644 index a9ed06ded042fe47826667b3d70acfe766181c21..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/pad_cn.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _cn_api_fluid_layers_pad: - -pad -------------------------------- - -.. py:function:: paddle.fluid.layers.pad(x, paddings, pad_value=0.0, name=None) - -:alias_main: paddle.nn.functional.pad -:alias: paddle.nn.functional.pad,paddle.nn.functional.common.pad -:old_api: paddle.fluid.layers.pad - - - -该OP在Tensor上填充一个由 ``pad_value`` 给出的常数值，填充宽度由 ``paddings`` 指定。 -其中，维度 ``i`` 中 ``x`` 内容前填充的值个数用 ``paddings[2*i]`` 表示，维度 ``i`` 中 ``x`` 内容后填充的值个数用 ``paddings[2*i+1]`` 表示。 - -**示例**： - -.. code-block:: text - - Given: - x = [[1, 2], [3, 4]] - - paddings = [0, 1, 1, 2] - - pad_value = 0 - - Return: - out = [[0, 1, 2, 0, 0] - [0, 3, 4, 0, 0] - [0, 0, 0, 0, 0]] - - -参数: - - **x** (Variable) — 多维Tensor，数据类型为float32 - - **paddings** (list of integers) — 整数列表，指定每个维度填充值的个数。维度 ``i`` 中 ``x`` 内容前填充的值个数用 ``paddings[2*i]`` 表示，维度 ``i`` 中 ``x`` 内容后填充的值个数用 ``paddings[2*i+1]`` 表示。 ``paddings`` 长度必须是 ``rank(x)×2`` - - **pad_value** (float32, 可选) — 用来填充的常量值，数据类型为float。默认值为0. - - **name** (str|None) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 - -返回： 填充后的Tensor，数据类型与输入 ``x`` 相同 - -返回类型： Variable - - -**代码示例** - -.. code-block:: python - - # x 为一个秩为2的张量 - import paddle.fluid as fluid - x = fluid.data(name='data', shape=[300, 300], dtype='float32') - out = fluid.layers.pad(x=x, paddings=[0, 1, 1, 2], pad_value=0.) - - diff --git a/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool1d_cn.rst b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..ae3683263fc3f3ea659259873028b7116d483c02 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool1d_cn.rst @@ -0,0 +1,54 @@ +.. _cn_api_nn_functional_adaptive_avg_pool1d: + + +adaptive_avg_pool1d +------------------------------- + +.. py:function:: paddle.nn.functional.adaptive_avg_pool1d(x, output_size, name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算1D的自适应平均池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度. + +.. note:: + 详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_AdaptiveAvgPool1d` 。 + + +参数 +::::::::: + - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, L]` 的3-D Tensor。其中 `N` 是batch size, `C` 是通道数, `L` 是输入特征的长度。 其数据类型为float32或者float64。 + - **output_size** (int): 算子输出特征图的长度，其数据类型为int。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +::::::::: +``Tensor``, 输入 `x` 经过自适应池化计算得到的目标3-D Tensor，其数据类型与输入相同。 + +抛出异常 +::::::::: + - ``ValueError`` - ``output_size`` 应是一个整数。 + +代码示例 +::::::::: + +.. code-block:: python + + # average adaptive pool1d + # suppose input data in shape of [N, C, L], `output_size` is m, + # output shape is [N, C, m], adaptive pool divide L dimension + # of input data into m grids averagely and performs poolings in each + # grid to get output. + # adaptive avg pool performs calculations as follow: + # + # for i in range(m): + # lstart = floor(i * L / m) + # lend = ceil((i + 1) * L / m) + # output[:, :, i] = sum(input[:, :, lstart: lend])/(lstart - lend) + # + import paddle + import paddle.nn.functional as F + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + pool_out = F.adaptive_avg_pool1d(data, output_size=16) + # pool_out shape: [1, 3, 16]) diff --git a/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool2d_cn.rst b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool2d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..cd5e3a087a4e187c9015c2a19a96112295012c15 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool2d_cn.rst @@ -0,0 +1,68 @@ +adaptive_avg_pool2d +------------------------------- + +.. py:function:: paddle.nn.functional.adaptive_avg_pool2d(x, output_size, data_format='NCHW', name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算2D的自适应平均池化。输入和输出都是4-D Tensor， +默认是以 `NCHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `H` 是输入特征的高度, `H` 是输入特征的宽度。 + +计算公式如下: + +.. math:: + + hstart &= floor(i * H_{in} / H_{out}) + + hend &= ceil((i + 1) * H_{in} / H_{out}) + + wstart &= floor(j * W_{in} / W_{out}) + + wend &= ceil((j + 1) * W_{in} / W_{out}) + + Output(i ,j) &= \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)} + + +参数 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，高度，宽度），即NCHW格式的4-D Tensor。 其数据类型为float16, float32, float64, int32或int64. + - **output_size** (int|list|turple): 算子输出特征图的尺寸，如果其是list或turple类型的数值，必须包含两个元素，H和W。H和W既可以是int类型值也可以是None，None表示与输入特征尺寸相同。 + - **data_format** (str): 输入和输出的数据格式，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +::::::::: +``Tensor``, 默认形状为（批大小，通道数，输出特征高度，输出特征宽度），即NCHW格式的4-D Tensor，其数据类型与输入相同。 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 + +代码示例 +::::::::: + +.. code-block:: python + + # adaptive avg pool2d + # suppose input data in shape of [N, C, H, W], `output_size` is [m, n], + # output shape is [N, C, m, n], adaptive pool divide H and W dimensions + # of input data into m * n grids averagely and performs poolings in each + # grid to get output. + # adaptive avg pool performs calculations as follow: + # + # for i in range(m): + # for j in range(n): + # hstart = floor(i * H / m) + # hend = ceil((i + 1) * H / m) + # wstart = floor(i * W / n) + # wend = ceil((i + 1) * W / n) + # output[:, :, i, j] = avg(input[:, :, hstart: hend, wstart: wend]) + # + import paddle + import numpy as np + paddle.disable_static() + input_data = np.random.rand(2, 3, 32, 32) + x = paddle.to_tensor(input_data) + # x.shape is [2, 3, 32, 32] + pool_out = paddle.nn.functional.adaptive_avg_pool2d( + x = x, + output_size=[3, 3]) + # pool_out.shape is [2, 3, 3, 3] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool3d_cn.rst b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool3d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..756f9d01ef220e7c42253d2a53572dba5f619f43 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_avg_pool3d_cn.rst @@ -0,0 +1,76 @@ +adaptive_avg_pool3d +------------------------------- + +.. py:function:: paddle.nn.functional.adaptive_avg_pool3d(x, output_size, data_format='NCDHW', name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算3D的自适应平均池化。输入和输出都是5-D Tensor， +默认是以 `NCDHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `D` 是特征图长度, `H` 是输入特征的高度, `H` 是输入特征的宽度。 + +计算公式如下: + +.. math:: + + dstart &= floor(i * D_{in} / D_{out}) + + dend &= ceil((i + 1) * D_{in} / D_{out}) + + hstart &= floor(j * H_{in} / H_{out}) + + hend &= ceil((j + 1) * H_{in} / H_{out}) + + wstart &= floor(k * W_{in} / W_{out}) + + wend &= ceil((k + 1) * W_{in} / W_{out}) + + Output(i ,j, k) &= \frac{sum(Input[dstart:dend, hstart:hend, wstart:wend])}{(dend - dstart) * (hend - hstart) * (wend - wstart)} + + + +参数 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，长度，高度，宽度），即NCDHW格式的5-D Tensor。 其数据类型为float16, float32, float64, int32或int64. + - **output_size** (int|list|turple): 算子输出特征图的尺寸，如果其是list或turple类型的数值，必须包含三个元素，D，H和W。D，H和W既可以是int类型值也可以是None，None表示与输入特征尺寸相同。 + - **data_format** (str): 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，D是特征长度，H是特征高度，W是特征宽度。默认值："NCDHW"。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +::::::::: +``Tensor``, 默认形状为（批大小，通道数，输出特征长度，输出特征高度，输出特征宽度），即NCDHW格式的5-D Tensor，其数据类型与输入相同。 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``data_format`` 既不是"NCDHW"也不是"NDHWC"。 + +代码示例 +::::::::: + +.. code-block:: python + + # adaptive avg pool3d + # suppose input data in shape of [N, C, D, H, W], `output_size` is [l, m, n], + # output shape is [N, C, l, m, n], adaptive pool divide D, H and W dimensions + # of input data into l * m * n grids averagely and performs poolings in each + # grid to get output. + # adaptive avg pool performs calculations as follow: + # + # for i in range(l): + # for j in range(m): + # for k in range(n): + # dstart = floor(i * D / l) + # dend = ceil((i + 1) * D / l) + # hstart = floor(j * H / m) + # hend = ceil((j + 1) * H / m) + # wstart = floor(k * W / n) + # wend = ceil((k + 1) * W / n) + # output[:, :, i, j, k] = + # avg(input[:, :, dstart:dend, hstart: hend, wstart: wend]) + import paddle + import numpy as np + paddle.disable_static() + input_data = np.random.rand(2, 3, 8, 32, 32) + x = paddle.to_tensor(input_data) + # x.shape is [2, 3, 8, 32, 32] + pool_out = paddle.nn.functional.adaptive_avg_pool3d( + x = x, + output_size=[3, 3, 3]) + # pool_out.shape is [2, 3, 3, 3, 3] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/functional/pooling/adaptive_max_pool1d_cn.rst b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_max_pool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..f88c16aa13961842246fcb6d87b5b8b7e675b929 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/pooling/adaptive_max_pool1d_cn.rst @@ -0,0 +1,55 @@ +.. _cn_api_nn_functional_adaptive_max_pool1d: + + +adaptive_max_pool1d +------------------------------- + +.. py:function:: paddle.nn.functional.adaptive_max_pool1d(x, output_size, return_indices=False, name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算1D的自适应最大值池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度. + +.. note:: + 详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_AdaptiveMaxPool1d` 。 + + +参数 +::::::::: + - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, L]` 的3-D Tensor。其中 `N` 是batch size, `C` 是通道数, `L` 是输入特征的长度。 其数据类型为float32或者float64。 + - **output_size** (int|list|tuple): 算子输出特征图的长度，其数据类型为int或list，tuple。 + - **return_indices** (bool): 如果设置为True，则会与输出一起返回最大值的索引，默认为False。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +::::::::: +``Tensor``, 输入 `x` 经过自适应池化计算得到的目标3-D Tensor，其数据类型与输入相同。 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``output_size`` 不是int类型值。 + +代码示例 +::::::::: + +.. code-block:: python + + # max adaptive pool1d + # suppose input data in shape of [N, C, L], `output_size` is m, + # output shape is [N, C, m], adaptive pool divide L dimension + # of input data into m grids averagely and performs poolings in each + # grid to get output. + # adaptive max pool performs calculations as follow: + # + # for i in range(m): + # lstart = floor(i * L / m) + # lend = ceil((i + 1) * L / m) + # output[:, :, i] = max(input[:, :, lstart: lend]) + # + import paddle + import paddle.nn.functional as F + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + pool_out = F.adaptive_max_pool1d(data, output_size=16) + # pool_out shape: [1, 3, 16]) diff --git a/doc/paddle/api/paddle/nn/functional/pooling/avg_pool1d_cn.rst b/doc/paddle/api/paddle/nn/functional/pooling/avg_pool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..0db33aac3c91669b90656ec32a05e1ba875ee843 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/pooling/avg_pool1d_cn.rst @@ -0,0 +1,53 @@ +.. _cn_api_nn_functional_avg_pool1d: + + +avg_pool1d +------------------------------- + +.. py:function:: paddle.nn.functional.avg_pool1d(x, kernel_size, stride=None, padding=0, count_include_pad=True, ceil_mode=False, name=None) + +该算子根据输入 `x` , `kernel_size` 等参数对一个输入Tensor计算1D的平均池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度。 + +.. note:: + 详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_AvgPool1d` 。 + + +参数 +::::::::: + - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, L]` 的3-D Tensor。其中 `N` 是batch size, `C` 是通道数, `L` 是输入特征的长度。 其数据类型为float32或者float64。 + - **kernel_size** (int|list|tuple): 池化核的尺寸大小. 如果kernel_size为list或tuple类型, 其必须包含一个整数. + - **stride** (int|list|tuple): 池化操作步长. 如果stride为list或tuple类型, 其必须包含一个整数. + - **padding** (string|int|list|tuple): 池化补零的方式. 如果padding是一个字符串，则必须为 `SAME` 或者 `VALID` 。 如果是turple或者list类型， 则应是 `[pad_left, pad_right]` 形式。如果padding是一个非0值，那么表示会在输入的两端都padding上同样长度的0。 + - **count_include_pad** (bool): 是否用额外padding的值计算平均池化结果，默认为True。 + - **ceil_mode** (bool): 是否用ceil函数计算输出的height和width，如果设置为False, 则使用floor函数来计算，默认为False。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +返回 +::::::::: +``Tensor``, 输入 `x` 经过平均池化计算得到的目标3-D Tensor，其数据类型与输入相同。 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``padding`` 是字符串但不是 "SAME" 和 "VALID" 。 + - ``ValueError`` - 如果 ``padding`` 是 "VALID" 但 `ceil_mode` 被设置为True。 + - ``ValueError`` - 如果 ``padding`` 是一个长度大于1的list或turple。 + - ``ShapeError`` - 如果输入x不是一个3-D Tensor。 + - ``ShapeError`` - 如果计算得到的输出形状小于等于0。 + + + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + pool_out = F.avg_pool1d(data, kernel_size=2, stride=2, padding=0) + # pool_out shape: [1, 3, 16] diff --git a/doc/paddle/api/paddle/nn/functional/pooling/max_pool1d_cn.rst b/doc/paddle/api/paddle/nn/functional/pooling/max_pool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..3ddefaa2d5f1a0c5b010cb3e3894fd3c1154656d --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/pooling/max_pool1d_cn.rst @@ -0,0 +1,56 @@ +.. _cn_api_nn_functional_max_pool1d: + + +max_pool1d +------------------------------- + +.. py:function:: paddle.nn.functional.max_pool1d(x, kernel_size, stride=None, padding=0, return_indices=False, ceil_mode=False, name=None) + +该算子根据输入 `x` , `kernel_size` 等参数对一个输入Tensor计算1D的最大值池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度。 + +.. note:: + 详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_MaxPool1d` 。 + + +参数 +::::::::: + - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, L]` 的3-D Tensor。其中 `N` 是batch size, `C` 是通道数, `L` 是输入特征的长度。 其数据类型为float32或者float64。 + - **kernel_size** (int|list|tuple): 池化核的尺寸大小. 如果kernel_size为list或tuple类型, 其必须包含一个整数. + - **stride** (int|list|tuple): 池化操作步长. 如果stride为list或tuple类型, 其必须包含一个整数. + - **padding** (string|int|list|tuple): 池化补零的方式. 如果padding是一个字符串，则必须为 `SAME` 或者 `VALID` 。如果是turple或者list类型， 则应是 `[pad_left, pad_right]` 形式。如果padding是一个非0值，那么表示会在输入的两端都padding上同样长度的0。 + - **return_indices** (bool): 是否返回最大值的索引，默认为False。 + - **ceil_mode** (bool): 是否用ceil函数计算输出的height和width，如果设置为False, 则使用floor函数来计算，默认为False。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +返回 +::::::::: +``Tensor``, 输入 `x` 经过最大值池化计算得到的目标3-D Tensor，其数据类型与输入相同。 + + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``padding`` 是字符串但不是 "SAME" 和 "VALID" 。 + - ``ValueError`` - 如果 ``padding`` 是 "VALID" 但 `ceil_mode` 被设置为True。 + - ``ValueError`` - 如果 ``padding`` 是一个长度大于1的list或turple。 + - ``ShapeError`` - 如果输入x不是一个3-D Tensor。 + - ``ShapeError`` - 如果计算得到的输出形状小于等于0。 + + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn.functional as F + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + pool_out = F.max_pool1d(data, kernel_size=2, stride=2, padding=0) + # pool_out shape: [1, 3, 16] + + pool_out, indices = F.max_pool1d(data, kernel_size=2, stride=2, padding=0, return_indices=True) + # pool_out shape: [1, 3, 16], indices shape: [1, 3, 16] diff --git a/doc/paddle/api/paddle/nn/functional/prelu_cn.rst b/doc/paddle/api/paddle/nn/functional/prelu_cn.rst deleted file mode 100644 index b1ea4cfb569fac4c885b8292ba07f022886e0934..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/prelu_cn.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _cn_api_fluid_layers_prelu: - -prelu -------------------------------- - - -.. py:function:: paddle.fluid.layers.prelu(x, mode, param_attr=None, name=None) - -:api_attr: 声明式编程模式（静态图) - - - -等式： - -.. math:: - y = max(0, x) + \alpha min(0, x) - -共提供三种激活方式： - -.. code-block:: text - - all: 所有元素使用同一个alpha值 - channel: 在同一个通道中的元素使用同一个alpha值 - element: 每一个元素有一个独立的alpha值 - - -参数： - - **x** （Variable）- 多维Tensor或LoDTensor，数据类型为float32。 - - **mode** (str) - 权重共享模式。 - - **param_attr** (ParamAttr，可选) - 可学习权重 :math:`[\alpha]` 的参数属性，可由ParamAttr创建。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - - -返回： 表示激活输出Tensor或LoDTensor，数据类型为float32。与输入形状相同。 - - -返回类型：Variable - - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - from paddle.fluid.param_attr import ParamAttr - x = fluid.data(name="x", shape=[None,5,10,10], dtype="float32") - mode = 'channel' - output = fluid.layers.prelu( - x,mode,param_attr=ParamAttr(name='alpha')) - - diff --git a/doc/paddle/api/paddle/nn/functional/relu6_cn.rst b/doc/paddle/api/paddle/nn/functional/relu6_cn.rst deleted file mode 100644 index 05c83c7e5e48c6fda17a075dd8bbd13f00c62c02..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/relu6_cn.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _cn_api_fluid_layers_relu6: - -relu6 -------------------------------- - -.. py:function:: paddle.fluid.layers.relu6(x, threshold=6.0, name=None) - -:alias_main: paddle.nn.functional.relu6 -:alias: paddle.nn.functional.relu6,paddle.nn.functional.activation.relu6 -:old_api: paddle.fluid.layers.relu6 - - - -relu6激活函数 - -.. math:: out=min(max(0, x), threshold) - - -参数: - - **x** (Variable) - 输入的多维 ``Tensor`` ，数据类型为：float32、float64。 - - **threshold** (float) - relu6的阈值。默认值为6.0 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回: 与 ``x`` 维度相同、数据类型相同的 ``Tensor``。 - -返回类型: Variable - - -**代码示例：** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - in1 = np.array([[-1,0],[2.5,7.8]]) - with fluid.dygraph.guard(): - x1 = fluid.dygraph.to_variable(in1) - out1 = fluid.layers.relu6(x=x1, threshold=6.0) - print(out1.numpy()) - # [[0. 0. ] - # [2.5 6. ]] diff --git a/doc/paddle/api/paddle/nn/functional/selu_cn.rst b/doc/paddle/api/paddle/nn/functional/selu_cn.rst deleted file mode 100644 index 4aee591bcc8dd87d0df0e9f0ef8faed224d5c5f1..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/selu_cn.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _cn_api_fluid_layers_selu: - -selu -------------------------------- - -.. py:function:: paddle.fluid.layers.selu(x, scale=None, alpha=None, name=None) - -:alias_main: paddle.nn.functional.selu -:alias: paddle.nn.functional.selu,paddle.nn.functional.activation.selu -:old_api: paddle.fluid.layers.selu - - - -SeLU激活函数，其公式如下： - -.. math:: - selu= \lambda* - \begin{cases} - x &\quad \text{ if } x>0 \\ - \alpha * e^x - \alpha &\quad \text{ if } x<=0 - \end{cases} - -输入 ``x`` 可以选择性携带LoD信息。输出和它共享此LoD信息(如果有)。 - -参数: - - **x** (Variable) - 输入变量，为数据类型为float32，float64的多维Tensor或者LoDTensor。 - - **scale** (float，可选) – 可选，表示SeLU激活函数中的λ的值，其默认值为 1.0507009873554804934193349852946。 详情请见： `Self-Normalizing Neural Networks `_。 - - **alpha** (float，可选) – 可选，表示SeLU激活函数中的α的值，其默认值为 1.6732632423543772848170429916717。 详情请见： `Self-Normalizing Neural Networks `_。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回：一个Tensor，shape和输入Tensor相同。 - -返回类型：Variable(Tensor|LoDTensor)，LoD信息与输入Tensor一致。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - inputs = fluid.layers.data(name="x", shape=[2, 2], dtype="float32") - output = fluid.layers.selu(inputs) - - exe = fluid.Executor(fluid.CPUPlace()) - exe.run(fluid.default_startup_program()) - - img = np.array([[0, 1],[2, 3]]).astype(np.float32) - - res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output]) - print(res) # [array([[0. , 1.050701],[2.101402, 3.152103]], dtype=float32)] - - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/softplus_cn.rst b/doc/paddle/api/paddle/nn/functional/softplus_cn.rst deleted file mode 100644 index 34ffe22854ec38f6e4d6379ff4925f002005901a..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/softplus_cn.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _cn_api_fluid_layers_softplus: - -softplus -------------------------------- - -.. py:function:: paddle.fluid.layers.softplus(x,name=None) - -:alias_main: paddle.nn.functional.softplus -:alias: paddle.nn.functional.softplus,paddle.nn.functional.activation.softplus -:old_api: paddle.fluid.layers.softplus - - - -softplus激活函数 - -.. math:: - out = \ln(1 + e^{x}) - -参数： - - **x** (Variable) - 张量（Tensor） - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 - -返回: 张量(Tensor) - -返回类型: 变量(Variable) - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.softplus(data) - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/softshrink_cn.rst b/doc/paddle/api/paddle/nn/functional/softshrink_cn.rst deleted file mode 100644 index b3a1af822dfe31a96ad9802e5b4795f1ea10624c..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/softshrink_cn.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _cn_api_fluid_layers_softshrink: - -softshrink -------------------------------- - -.. py:function:: paddle.fluid.layers.softshrink(x, alpha=None) - -:alias_main: paddle.nn.functional.softshrink -:alias: paddle.nn.functional.softshrink,paddle.nn.functional.activation.softshrink -:old_api: paddle.fluid.layers.softshrink - - - -Softshrink激活函数 - -.. math:: - out = \begin{cases} - x - \alpha, \text{if } x > \alpha \\ - x + \alpha, \text{if } x < -\alpha \\ - 0, \text{otherwise} - \end{cases} - -参数： - - **x** (Variable0 - 张量（Tensor） - - **alpha** (float) - 上面公式中alpha的值 - -返回: 张量(Tensor) - -返回类型: 变量(Variable) - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.softshrink(data) - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/softsign_cn.rst b/doc/paddle/api/paddle/nn/functional/softsign_cn.rst deleted file mode 100644 index ca46bf270800dd0764d000c9b3275a45553c0bb1..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/softsign_cn.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _cn_api_fluid_layers_softsign: - -softsign -------------------------------- - -.. py:function:: paddle.fluid.layers.softsign(x,name=None) - -:alias_main: paddle.nn.functional.softsign -:alias: paddle.nn.functional.softsign,paddle.nn.functional.activation.softsign -:old_api: paddle.fluid.layers.softsign - - - - -softsign激活函数 - -.. math:: - out = \frac{x}{1 + |x|} - -参数： - - **x** (Variable) - 张量（Tensor） - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 - -返回: 张量(Tensor) - -返回类型: 变量(Variable) - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.softsign(data) - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/tanh_cn.rst b/doc/paddle/api/paddle/nn/functional/tanh_cn.rst deleted file mode 100644 index c5fbd21242439402ebda6b4fcd5e6aedec699aa7..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/functional/tanh_cn.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _cn_api_fluid_layers_tanh: - -tanh -------------------------------- - -.. py:function:: paddle.fluid.layers.tanh(x, name=None) - - - - - -tanh 激活函数 - -.. math:: - out = \frac{e^{x} - e^{-x}}{e^{x} + e^{-x}} - - -参数: - - - **x** - Tanh算子的输入 - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 - -返回: 张量(Tensor) - -返回类型: 变量(Variable) - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.tanh(data) - - - - - - - - - - - - - diff --git a/doc/paddle/api/paddle/nn/functional/vision/affine_grid_cn.rst b/doc/paddle/api/paddle/nn/functional/vision/affine_grid_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..287116d9f5f6845eb0f874a78c329ca49676b14d --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/vision/affine_grid_cn.rst @@ -0,0 +1,34 @@ +.. _cn_api_fluid_layers_affine_grid: + +affine_grid +------------------------------- + +.. py:function:: paddle.fluid.layers.affine_grid(theta, out_shape, name=None) + +:alias_main: paddle.nn.functional.affine_grid +:alias: paddle.nn.functional.affine_grid,paddle.nn.functional.vision.affine_grid +:old_api: paddle.fluid.layers.affine_grid + + + +该OP用于生成仿射变换前后的feature maps的坐标映射关系。在视觉应用中，根据该OP得到的映射关系，将输入feature map的像素点变换到对应的坐标，就得到了经过仿射变换的feature map。 + +参数： + - **theta** (Variable) - Shape为 ``[batch_size, 2, 3]`` 的Tensor，表示batch_size个 ``2X3`` 的变换矩阵。数据类型支持float32，float64。 + - **out_shape** (Variable | list | tuple) - 类型可以是1-D Tensor、list或tuple。用于表示在仿射变换中的输出的shape，其格式 ``[N, C, H, W]`` ，分别为输出feature map的batch size、channel数量、高和宽。数据类型支持int32。 + - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:api_guide_Name ，默认值为None。 + +返回： Variable。Shape为 ``[N, H, W, 2]`` 的4-D Tensor，表示仿射变换前后的坐标的映射关系。其中，N、H、W分别为仿射变换中输出feature map的batch size、高和宽。 数据类型与 ``theta`` 一致。 + +返回类型：Variable + +**代码示例：** + +.. code-block:: python + + import paddle.fluid as fluid + theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32") + out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32") + data = fluid.layers.affine_grid(theta, out_shape) + # or + data = fluid.layers.affine_grid(theta, [5, 3, 28, 28]) diff --git a/doc/paddle/api/paddle/nn/functional/vision/pixel_shuffle_cn.rst b/doc/paddle/api/paddle/nn/functional/vision/pixel_shuffle_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..07b29dd8892aece514291f781a5e3918dc882834 --- /dev/null +++ b/doc/paddle/api/paddle/nn/functional/vision/pixel_shuffle_cn.rst @@ -0,0 +1,45 @@ +.. _cn_api_fluid_layers_pixel_shuffle: + +pixel_shuffle +------------------------------- + +.. py:function:: paddle.fluid.layers.pixel_shuffle(x, upscale_factor) + +:alias_main: paddle.nn.functional.pixel_shuffle +:alias: paddle.nn.functional.pixel_shuffle,paddle.nn.functional.vision.pixel_shuffle +:old_api: paddle.fluid.layers.pixel_shuffle + + + +该OP将一个形为[N, C, H, W]的Tensor重新排列成形为 [N, C/r**2, H*r, W*r] 的Tensor。这样做有利于实现步长（stride）为1/r的高效sub-pixel（亚像素）卷积。详见Shi等人在2016年发表的论文 `Real Time Single Image and Video Super Resolution Using an Efficient Sub Pixel Convolutional Neural Network `_ 。 + +.. code-block:: text + + 给定一个形为 x.shape = [1, 9, 4, 4] 的4-D张量 + 设定：upscale_factor=3 + 那么输出张量的形为：[1, 1, 12, 12] + +参数： + - **x** （Variable）- 维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。 + - **upscale_factor** （int）- 增大空间分辨率的增大因子 + + +返回：根据新的维度信息进行重组的张量 + +返回类型： Variable + +抛出异常： ``ValueError`` - 如果upscale_factor的平方不能整除输入的通道维度(C)的大小。 + + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + input = fluid.layers.data(name="input", shape=[9,4,4]) + output = fluid.layers.pixel_shuffle(x=input, upscale_factor=3) + + + + + diff --git a/doc/paddle/api/paddle/nn/layer/activation/ELU_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/ELU_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..f2cb3cfb242282ccca4ffa6b7355adb2a9e9e1ca --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/ELU_cn.rst @@ -0,0 +1,41 @@ +.. _cn_api_nn_ELU: + +ELU +------------------------------- +.. py:class:: paddle.nn.ELU(alpha=1.0, name=None) + +ELU激活层（ELU Activation Operator） + +根据 `Exponential Linear Units `_ 对输入Tensor中每个元素应用以下计算。 + +.. math:: + + ELU(x) = max(0, x) + min(0, \alpha * (e^{x} − 1)) + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - alpha (float, 可选) - ELU的alpha值，默认值为1.0。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([[-1, 6],[1, 15.6]])) + m = paddle.nn.ELU(0.2) + out = m(x) + # [[-0.12642411 6. ] + # [ 1. 15.6 ]] diff --git a/doc/paddle/api/paddle/nn/layer/activation/GELU_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/GELU_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..3493bf7f6ea266f1c392908fc933c25a664af549 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/GELU_cn.rst @@ -0,0 +1,50 @@ +.. _cn_api_nn_GELU: + +GELU +------------------------------- +.. py:class:: paddle.nn.GELU(approximate=False, name=None) + +GELU激活层（GELU Activation Operator） + +逐元素计算 GELU激活函数。更多细节请参考 `Gaussian Error Linear Units `_ 。 + +如果使用近似计算： + +.. math:: + GELU(x) = 0.5 * x * (1 + tanh(\sqrt{\frac{2}{\pi}} * (x + 0.044715x^{3}))) + +如果不使用近似计算： + +.. math:: + GELU(x) = 0.5 * x * (1 + erf(\frac{x}{\sqrt{2}})) + + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - approximate (bool, 可选) - 是否使用近似计算，默认值为 False，即不使用近似计算。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([[-1, 0.5],[1, 1.5]])) + + m = paddle.nn.GELU() + out = m(x) # [-0.158655 0.345731 0.841345 1.39979] + + m = paddle.nn.GELU(True) + out = m(x) # [-0.158808 0.345714 0.841192 1.39957] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Hardshrink_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Hardshrink_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..61ba40a8f6e7b9b1a4f09fda94c26ea6b9c34830 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Hardshrink_cn.rst @@ -0,0 +1,43 @@ +.. _cn_api_nn_Hardshrink: + +Hardshrink +------------------------------- +.. py:class:: paddle.nn.Hardshrink(threshold=0.5, name=None) + +Hardshrink激活层 + +.. math:: + + Hardshrink(x)= + \left\{ + \begin{aligned} + &x, & & if \ x > threshold \\ + &x, & & if \ x < -threshold \\ + &0, & & if \ others + \end{aligned} + \right. + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - threshold (float, 可选) - Hardshrink激活计算公式中的threshold值。默认值为0.5。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_variable(np.array([-1, 0.3, 2.5])) + m = paddle.nn.Hardshrink() + out = m(x) # [-1., 0., 2.5] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Hardtanh_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Hardtanh_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d3955f41d3d8a9177ec1d0cb42a8103fa39a83ea --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Hardtanh_cn.rst @@ -0,0 +1,45 @@ +.. _cn_api_nn_Hardtanh: + +Hardtanh +------------------------------- +.. py:class:: paddle.nn.Hardtanh(min=-1.0, max=1.0, name=None) + +Hardtanh激活层（Hardtanh Activation Operator）。计算公式如下： + +.. math:: + + Hardtanh(x)= + \left\{ + \begin{aligned} + &max, & & if \ x > max \\ + &min, & & if \ x < min \\ + &x, & & if \ others + \end{aligned} + \right. + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - min (float, 可选) - Hardtanh激活计算公式中的min值。默认值为-1。 + - max (float, 可选) - Hardtanh激活计算公式中的max值。默认值为1。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-1.5, 0.3, 2.5])) + m = paddle.nn.Hardtanh() + out = m(x) # # [-1., 0.3, 1.] diff --git a/doc/paddle/api/paddle/nn/layer/activation/LeakyReLU_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/LeakyReLU_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..62d710903d488957b9360f88a448c4c267212023 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/LeakyReLU_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_nn_LeakyReLU: + +LeakyReLU +------------------------------- +.. py:class:: paddle.nn.LeakyReLU(negative_slope=0.01, name=None) + +LeakyReLU 激活层 + +.. math:: + + LeakyReLU(x)= + \left\{ + \begin{aligned} + &x, & & if \ x >= 0 \\ + &negative\_slope * x, & & otherwise \\ + \end{aligned} + \right. \\ + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - negative_slope (float，可选) - :math:`x < 0` 时的斜率。默认值为0.01。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + m = paddle.nn.LeakyReLU() + x = paddle.to_tensor(np.array([-2, 0, 1], 'float32')) + out = m(x) # [-0.02, 0., 1.] diff --git a/doc/paddle/api/paddle/nn/layer/activation/LogSigmoid_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/LogSigmoid_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..754f59fce5b6ab07dd2c0c699d7f86bff9bd93bb --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/LogSigmoid_cn.rst @@ -0,0 +1,36 @@ +.. _cn_api_nn_LogSigmoid: + +LogSigmoid +------------------------------- +.. py:class:: paddle.nn.LogSigmoid(name=None) + +LogSigmoid激活层。计算公式如下： + +.. math:: + + LogSigmoid(x) = \log \frac{1}{1 + e^{-x}} + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([1.0, 2.0, 3.0, 4.0])) + m = paddle.nn.LogSigmoid() + out = m(x) # [-0.313262 -0.126928 -0.0485874 -0.0181499] diff --git a/doc/paddle/api/paddle/nn/layer/activation/LogSoftmax_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/LogSoftmax_cn.rst index 72ed06ecc1caa1b4e7296274e50df6dc623da1e3..96bbc3a886f9535bf02cb1954645d5182e669120 100644 --- a/doc/paddle/api/paddle/nn/layer/activation/LogSoftmax_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/activation/LogSoftmax_cn.rst @@ -2,46 +2,46 @@ LogSoftmax ------------------------------- -.. py:class:: paddle.nn.LogSoftmax(axis=None) +.. py:class:: paddle.nn.LogSoftmax(axis=-1, name=None) -:alias_main: paddle.nn.LogSoftmax -:alias: paddle.nn.LogSoftmax,paddle.nn.layer.LogSoftmax,paddle.nn.layer.activation.LogSoftmax - - - - -**LogSoftmax激活层：** +LogSoftmax激活层，计算公式如下： .. math:: - \\output = \frac{1}{1 + e^{-input}}\\ + Out[i, j] = log(softmax(x)) + = log(\\frac{\exp(X[i, j])}{\sum_j(exp(X[i, j])}) -参数: - - **axis** (int, 可选) - 指示进行LogSoftmax计算的维度索引，其范围应为 :math:`[-1，rank-1]` ，其中rank是输入变量的秩。默认值：None（与-1效果相同，表示对最后一维做LogSoftmax操作）。 +参数 +:::::::::: + - axis (int, 可选) - 指定对输入Tensor进行运算的轴。``axis`` 的有效范围是[-D, D)，D是输入Tensor的维度， ``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回：无 +形状: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 -**代码示例** +代码示例 +::::::::: -.. code-block:: python +.. code-block:: python - import paddle.fluid as fluid - import paddle.nn as nn + import paddle import numpy as np - data = np.array([[[-2.0, 3.0, -4.0, 5.0], - [3.0, -4.0, 5.0, -6.0], - [-7.0, -8.0, 8.0, 9.0]], - [[1.0, -2.0, -3.0, 4.0], - [-5.0, 6.0, 7.0, -8.0], - [6.0, 7.0, 8.0, 9.0]]]).astype('float32') - my_log_softnmax = nn.LogSoftmax() - with fluid.dygraph.guard(): - data = fluid.dygraph.to_variable(data) - res = my_log_softnmax(data) - # [[[ -7.1278396 -2.1278396 -9.127839 -0.12783948] - # [ -2.1270514 -9.127051 -0.12705144 -11.127051 ] - # [-16.313261 -17.313261 -1.3132617 -0.31326184]] - # [[ -3.0518122 -6.051812 -7.051812 -0.051812 ] - # [-12.313267 -1.3132664 -0.3132665 -15.313267 ] - # [ -3.4401896 -2.4401896 -1.4401896 -0.44018966]]] + paddle.disable_static() + + x = np.array([[[-2.0, 3.0, -4.0, 5.0], + [3.0, -4.0, 5.0, -6.0], + [-7.0, -8.0, 8.0, 9.0]], + [[1.0, -2.0, -3.0, 4.0], + [-5.0, 6.0, 7.0, -8.0], + [6.0, 7.0, 8.0, 9.0]]], 'float32') + m = paddle.nn.LogSoftmax() + x = paddle.to_tensor(x) + out = m(x) + # [[[ -7.1278396 -2.1278396 -9.127839 -0.12783948] + # [ -2.1270514 -9.127051 -0.12705144 -11.127051 ] + # [-16.313261 -17.313261 -1.3132617 -0.31326184]] + # [[ -3.0518122 -6.051812 -7.051812 -0.051812 ] + # [-12.313267 -1.3132664 -0.3132665 -15.313267 ] + # [ -3.4401896 -2.4401896 -1.4401896 -0.44018966]]] diff --git a/doc/paddle/api/paddle/nn/layer/activation/PReLU_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/PReLU_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d36cee798c13583d8abbe05aacc8d3e44c791bbc --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/PReLU_cn.rst @@ -0,0 +1,54 @@ +.. _cn_api_nn_PReLU: + +PReLU +------------------------------- +.. py:class:: paddle.nn.PReLU(num_parameters=1, init=0.25, weight_attr=None, name=None) + +PReLU激活层（PReLU Activation Operator）。计算公式如下： + +如果使用近似计算： + +.. math:: + + PReLU(x) = max(0, x) + weight * min(0, x) + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - num_parameters (int, 可选) - 可训练`weight`数量，支持2种输入：1 - 输入中的所有元素使用同一个`weight`值; 输入的通道数 - 在同一个通道中的元素使用同一个`weight`值。默认为1。 + - init (float, 可选) - `weight`的初始值。默认为0.25。 + - weight_attr (ParamAttr, 可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor，默认数据类型为float32。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + paddle.set_default_dtype("float64") + + data = np.array([[[[-2.0, 3.0, -4.0, 5.0], + [ 3.0, -4.0, 5.0, -6.0], + [-7.0, -8.0, 8.0, 9.0]], + [[ 1.0, -2.0, -3.0, 4.0], + [-5.0, 6.0, 7.0, -8.0], + [ 6.0, 7.0, 8.0, 9.0]]]], 'float64') + x = paddle.to_tensor(data) + m = paddle.nn.PReLU(1, 0.25) + out = m(x) + # [[[[-0.5 , 3. , -1. , 5. ], + # [ 3. , -1. , 5. , -1.5 ], + # [-1.75, -2. , 8. , 9. ]], + # [[ 1. , -0.5 , -0.75, 4. ], + # [-1.25, 6. , 7. , -2. ], + # [ 6. , 7. , 8. , 9. ]]]] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/layer/activation/ReLU6_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/ReLU6_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..0ba5f2af0ec631c33f97e3091044309d20906868 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/ReLU6_cn.rst @@ -0,0 +1,36 @@ +.. _cn_api_nn_ReLU6: + +ReLU6 +------------------------------- +.. py:class:: paddle.nn.ReLU6(name=None) + +ReLU6激活层 + +.. math:: + + ReLU6(x) = min(max(0,x), 6) + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-1, 0.3, 6.5])) + m = paddle.nn.ReLU6() + out = m(x) # [0, 0.3, 6] diff --git a/doc/paddle/api/paddle/nn/layer/activation/ReLU_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/ReLU_cn.rst index 2e8640fa3796d6e7cfcfcb13600b38d08209cfcb..ac39225bf61db1653fc7d62a7339a824f992aa0e 100644 --- a/doc/paddle/api/paddle/nn/layer/activation/ReLU_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/activation/ReLU_cn.rst @@ -2,38 +2,35 @@ ReLU ------------------------------- -.. py:class:: paddle.nn.ReLU(inplace=False) +.. py:class:: paddle.nn.ReLU(name=None) -:alias_main: paddle.nn.ReLU -:alias: paddle.nn.ReLU,paddle.nn.layer.ReLU,paddle.nn.layer.activation.ReLU -:update_api: paddle.fluid.layers.relu - - - - -**ReLU（Rectified Linear Unit）激活层：** +ReLU激活层（Rectified Linear Unit）。计算公式如下： .. math:: - \\Out = max(X, 0)\\ + ReLU(x) = max(0, x) -其中，:math:`X` 为输入的 Tensor +其中，:math:`x` 为输入的 Tensor -参数: - - **inplace** （bool，可选）- 如果 ``inplace`` 为 ``True``，则 ``ReLU`` 的输入和输出是同一个变量，否则 ``ReLU`` 的输入和输出是不同的变量。默认值：``False``。请注意，如果 ``ReLU`` 的输入同时是其它OP的输入，则 ``inplace`` 必须为False。 +参数 +:::::::::: + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回：无 +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 -**代码示例** +代码示例 +::::::::: -.. code-block:: python +.. code-block:: python - import paddle.fluid as fluid - import paddle.nn as nn + import paddle import numpy as np + + paddle.disable_static() - data = np.array([-2, 0, 1]).astype('float32') - my_relu = nn.ReLU() - with fluid.dygraph.guard(): - data = fluid.dygraph.to_variable(data) - res = my_relu(data) # [0, 0, 1] + x = paddle.to_tensor(np.array([-2, 0, 1]).astype('float32')) + m = paddle.nn.ReLU() + out = m(x) # [0., 0., 1.] diff --git a/doc/paddle/api/paddle/nn/layer/activation/SELU_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/SELU_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..2bd2ce11b2bf60c8e1aafd5f1fe2d44c51ee1f30 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/SELU_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_nn_SELU: + +SELU +------------------------------- +.. py:class:: paddle.nn.SELU(scale=1.0507009873554804934193349852946, alpha=1.6732632423543772848170429916717, name=None) + +SELU激活层 + +.. math:: + + SELU(x)= scale * + \begin{cases} + x, \text{if } x > 0 \\ + alpha * e^{x} - alpha, \text{if } x <= 0 + \end{cases} + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - scale (float, 可选) - SELU激活计算公式中的scale值，必须大于1.0。默认值为1.0507009873554804934193349852946。 + - alpha (float, 可选) - SELU激活计算公式中的alpha值，必须大于等于零。默认值为1.6732632423543772848170429916717。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([[0.0, 1.0],[2.0, 3.0]])) + m = paddle.nn.SELU() + out = m(x) # [[0, 1.050701],[2.101402, 3.152103]] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Sigmoid_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Sigmoid_cn.rst index 0754265b2131c42b1d2e0a910e89163f4681f903..560bc22dd57ddd2d4c1e60b0a7e238e169bc49ea 100644 --- a/doc/paddle/api/paddle/nn/layer/activation/Sigmoid_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/activation/Sigmoid_cn.rst @@ -1,3 +1,40 @@ +.. _cn_api_nn_layer_Sigmoid: + Sigmoid ------------------------------- -**版本升级，文档正在开发中** + +.. py:class:: paddle.nn.layer.Sigmoid(name=None) + +该接口用于创建一个 ``Sigmoid`` 的可调用类。 这个类可以计算输入 `x` 经过激活函数 `sigmoid` 之后的值。 + + .. math:: + + output = \frac{1}{1 + e^{-x}} + +参数 +:::::::: + - **name** （str，可选）- 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +形状 +:::::::: + - **x** （Tensor）- N-D tensor, 可以支持的数据类型是float16，float32，float64。 + +返回 +:::::::: + 返回计算 ``Sigmoid`` 的可调用对象。 + + +代码示例 +:::::::: + +.. code-block:: python + + import numpy as np + import paddle + + paddle.disable_static() + input_data = np.array([1.0, 2.0, 3.0, 4.0]).astype('float32') + m = paddle.nn.Sigmoid() + x = paddle.to_variable(input_data) + output = m(x) + print(output.numpy()) # [0.7310586, 0.880797, 0.95257413, 0.98201376 diff --git a/doc/paddle/api/paddle/nn/layer/activation/Softmax_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Softmax_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..ba6f60076ea114a210ac1d0a4b919a0b99a02a0f --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Softmax_cn.rst @@ -0,0 +1,117 @@ +.. _cn_api_nn_Softmax: + +Softmax +------------------------------- +.. py:class:: paddle.nn.Softmax(axis=-1, name=None) + +Softmax激活层，OP的计算过程如下： + +步骤1：输入 ``x`` 的 ``axis`` 维会被置换到最后一维； + +步骤2：将输入 ``x`` 在逻辑上变换为二维矩阵。二维矩阵第一维（列长度）是输入除最后一维之外的其他维度值的乘积，第二维（行长度）和输入 ``axis`` 维的长度相同；对于矩阵的每一行，softmax操作对其进行重新缩放，使得该行的每个元素在 \[0,1\] 范围内，并且总和为1； + +步骤3：softmax操作执行完成后，执行步骤1和步骤2的逆运算，将二维矩阵恢复至和输入 ``x`` 相同的维度。 + +上述步骤2中softmax操作计算过程如下： + + - 对于二维矩阵的每一行，计算K维向量（K是输入第 ``axis`` 维的长度）中指定位置的指数值和全部位置指数值的和。 + + - 指定位置指数值与全部位置指数值之和的比值就是softmax操作的输出。 + +对于二维矩阵中的第i行和第j列有： + +.. math:: + + Softmax[i, j] = \frac{\exp(x[i, j])}{\sum_j(exp(x[i, j])} + +- 示例1（矩阵一共有三维。axis = -1，表示沿着最后一维（即第三维）做softmax操作） + +.. code-block:: text + + # input + + x.shape = [2, 3, 4] + + x.data = [[[2.0, 3.0, 4.0, 5.0], + [3.0, 4.0, 5.0, 6.0], + [7.0, 8.0, 8.0, 9.0]], + [[1.0, 2.0, 3.0, 4.0], + [5.0, 6.0, 7.0, 8.0], + [6.0, 7.0, 8.0, 9.0]]] + + axis = -1 + + # output + + out.shape = [2, 3, 4] + + out.data = [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + [0.0320586 , 0.08714432, 0.23688282, 0.64391426], + [0.07232949, 0.19661193, 0.19661193, 0.53444665]], + [[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + [0.0320586 , 0.08714432, 0.23688282, 0.64391426], + [0.0320586 , 0.08714432, 0.23688282, 0.64391426]]] + +- 示例2（矩阵一共有三维。axis = 1，表示沿着第二维做softmax操作） + +.. code-block:: text + + # input + + x.shape = [2, 3, 4] + + x.data = [[[2.0, 3.0, 4.0, 5.0], + [3.0, 4.0, 5.0, 6.0], + [7.0, 8.0, 8.0, 9.0]], + [[1.0, 2.0, 3.0, 4.0], + [5.0, 6.0, 7.0, 8.0], + [6.0, 7.0, 8.0, 9.0]]] + + axis = 1 + + # output + + out.shape = [2, 3, 4] + + out.data = [[[0.00657326, 0.00657326, 0.01714783, 0.01714783], + [0.01786798, 0.01786798, 0.04661262, 0.04661262], + [0.97555875, 0.97555875, 0.93623955, 0.93623955]], + [[0.00490169, 0.00490169, 0.00490169, 0.00490169], + [0.26762315, 0.26762315, 0.26762315, 0.26762315], + [0.72747516, 0.72747516, 0.72747516, 0.72747516]]] + +参数 +:::::::::: + - axis (int, 可选) - 指定对输入Tensor进行运算的轴。``axis`` 的有效范围是[-D, D)，D是输入Tensor的维度， ``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +:::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = np.array([[[-2.0, 3.0, -4.0, 5.0], + [3.0, -4.0, 5.0, -6.0], + [-7.0, -8.0, 8.0, 9.0]], + [[1.0, -2.0, -3.0, 4.0], + [-5.0, 6.0, 7.0, -8.0], + [6.0, 7.0, 8.0, 9.0]]], 'float32') + x = paddle.to_tensor(x) + m = paddle.nn.Softmax() + out = m(x) + # [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.07232949, 0.19661193, 0.19661193, 0.53444665]], + # [[0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.0320586 , 0.08714432, 0.23688282, 0.64391426], + # [0.0320586 , 0.08714432, 0.23688282, 0.64391426]]] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Softplus_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Softplus_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..cce23fcb7046fbdc66eb61a099517077a6378750 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Softplus_cn.rst @@ -0,0 +1,39 @@ +.. _cn_api_nn_Softplus: + +Softplus +------------------------------- +.. py:class:: paddle.nn.Softplus(beta=1, threshold=20, name=None) + +Softplus激活层 + +.. math:: + + Softplus(x) = \frac{1}{beta} * \log(1 + e^{beta * x}) \\ + \text{为了保证数值稳定性, 当}\,beta * x > threshold\,\text{时，函数转变为线性函数x}. + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - beta (float, 可选) - Softplus激活计算公式中的beta值。默认值为1。 + - threshold (float, 可选) - Softplus激活计算公式中的threshold值。默认值为20。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + m = paddle.nn.Softplus() + out = m(x) # [0.513015, 0.598139, 0.744397, 0.854355] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Softshrink_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Softshrink_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d04cf74e560a9176824a324d7ecd340e227b59dc --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Softshrink_cn.rst @@ -0,0 +1,41 @@ +.. _cn_api_nn_Softshrink: + +Softshrink +------------------------------- +.. py:class:: paddle.nn.Softshrink(threshold=0.5, name=None) + +Softshrink激活层 + +.. math:: + + Softshrink(x)= \begin{cases} + x - threshold, \text{if } x > threshold \\ + x + threshold, \text{if } x < -threshold \\ + 0, \text{otherwise} + \end{cases} + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - threshold (float, 可选) - Softshrink激活计算公式中的threshold值，必须大于等于零。默认值为0.5。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.9, -0.2, 0.1, 0.8])) + m = paddle.nn.Softshrink() + out = m(x) # [-0.4, 0, 0, 0.3] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Softsign_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Softsign_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..8029d97d80dc9bcf506bb127fc2499f7564029de --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Softsign_cn.rst @@ -0,0 +1,36 @@ +.. _cn_api_nn_Softsign: + +Softsign +------------------------------- +.. py:class:: paddle.nn.Softsign(name=None) + +Softsign激活层 + +.. math:: + + Softsign(x) = \frac{x}{1 + |x|} + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + m = paddle.nn.Softsign() + out = m(x) # [-0.285714, -0.166667, 0.0909091, 0.230769] diff --git a/doc/paddle/api/paddle/nn/layer/activation/Tanh_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Tanh_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..4f97cdb57f053dd24bca94e945afae7ffa6fd04a --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Tanh_cn.rst @@ -0,0 +1,35 @@ +.. _cn_api_nn_Tanh: + +Tanh +------------------------------- +.. py:class:: paddle.nn.Tanh(name=None) + +Tanh激活层 + +.. math:: + Tanh(x) = \frac{e^{x} - e^{-x}}{e^{x} + e^{-x}} + + +参数 +:::::::::: + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + m = paddle.nn.Tanh() + out = m(x) + print(out.numpy()) + # [-0.37994896 -0.19737532 0.09966799 0.29131261] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/layer/activation/Tanhshrink_cn.rst b/doc/paddle/api/paddle/nn/layer/activation/Tanhshrink_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..6c657fd800a7d4a475bb0277df42bf9dfea7eeb2 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/activation/Tanhshrink_cn.rst @@ -0,0 +1,36 @@ +.. _cn_api_nn_Tanhshrink: + +Tanhshrink +------------------------------- +.. py:class:: paddle.nn.Tanhshrink(name=None) + +Tanhshrink激活层 + +.. math:: + + Tanhshrink(x) = x - tanh(x) + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状: +:::::::::: + - input: 任意形状的Tensor。 + - output: 和input具有相同形状的Tensor。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.to_tensor(np.array([-0.4, -0.2, 0.1, 0.3])) + m = paddle.nn.Tanhshrink() + out = m(x) # [-0.020051, -0.00262468, 0.000332005, 0.00868739] diff --git a/doc/paddle/api/paddle/nn/layer/common/AlphaDropout_cn.rst b/doc/paddle/api/paddle/nn/layer/common/AlphaDropout_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..8dfdac7935a55010b9891b9835b8b2446629e75c --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/AlphaDropout_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_nn_AlphaDropout: + +AlphaDropout +------------------------------- + +.. py:function:: paddle.nn.AlphaDropout(p=0.5, name=None) + +AlphaDropout是一种具有自归一化性质的dropout。均值为0，方差为1的输入，经过AlphaDropout计算之后，输出的均值和方差与输入保持一致。AlphaDropout通常与SELU激活函数组合使用。论文请参考: `Self-Normalizing Neural Networks `_ + +在动态图模式下，请使用模型的 `eval()` 方法切换至测试阶段。 + +.. note:: + 对应的 `functional方法` 请参考: :ref:`cn_api_nn_functional_alpha_dropout` 。 + +参数 +::::::::: + - **p** (float): 将输入节点置0的概率，即丢弃概率。默认: 0.5。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +经过AlphaDropout之后的结果，与输入x形状相同的 `Tensor` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + x = np.array([[-1, 1], [-1, 1]]).astype('float32') + x = paddle.to_tensor(x) + m = paddle.nn.AlphaDropout(p=0.5) + y_train = m(x) + m.eval() # switch the model to test phase + y_test = m(x) + print(x.numpy()) + print(y_train.numpy()) + # [[-0.10721093, 1.6655989 ], [-0.7791938, -0.7791938]] (randomly) + print(y_test.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/common/BilinearTensorProduct_cn.rst b/doc/paddle/api/paddle/nn/layer/common/BilinearTensorProduct_cn.rst deleted file mode 100644 index 59b18c17a32951135e431ef036a6d32771651399..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/nn/layer/common/BilinearTensorProduct_cn.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _cn_api_fluid_dygraph_BilinearTensorProduct: - -BilinearTensorProduct -------------------------------- - -.. py:class:: paddle.fluid.dygraph.BilinearTensorProduct(input1_dim, input2_dim, output_dim, name=None, act=None, param_attr=None, bias_attr=None, dtype="float32") - -:alias_main: paddle.nn.BilinearTensorProduct -:alias: paddle.nn.BilinearTensorProduct,paddle.nn.layer.BilinearTensorProduct,paddle.nn.layer.common.BilinearTensorProduct -:old_api: paddle.fluid.dygraph.BilinearTensorProduct - - - -该接口用于构建 ``BilinearTensorProduct`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。双线性乘积计算式子如下。 - -.. math:: - - out_{i} = x * W_{i} * {y^\mathrm{T}}, i=0,1,...,size-1 - -式中， - -- :math:`x` ： 第一个输入，分别包含M个元素，维度为 :math:`[batch\_size, M]` -- :math:`y` ：第二个输入，分别包含N个元素，维度为 :math:`[batch\_size, N]` -- :math:`W_i` ：第i个学习到的权重，维度为 :math:`[M,N]` -- :math:`out_i` ：输出的第i个元素 -- :math:`y^T` ： :math:`y` 的转置 - - -参数： - - **input1_dim** (int) – 第一个输入的维度大小。 - - **input1_dim** (int) – 第二个输入的维度大小。 - - **output_dim** (int) – 输出的维度。 - - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - - **act** (str，可选) – 对输出应用的激励函数。默认值为None。 - - **param_attr** (ParamAttr) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **bias_attr** (ParamAttr) – 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 - - **dtype** (str, 可选) - 数据类型，可以为"float32"或"float64"。默认值为"float32"。 - -返回：维度为[batch_size, size]的2D Tensor，数据类型与输入数据类型相同。 - -返回类型： Variable - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy - - with fluid.dygraph.guard(): - layer1 = numpy.random.random((5, 5)).astype('float32') - layer2 = numpy.random.random((5, 4)).astype('float32') - bilinearTensorProduct = fluid.dygraph.nn.BilinearTensorProduct( - input1_dim=5, input2_dim=4, output_dim=1000) - ret = bilinearTensorProduct(fluid.dygraph.base.to_variable(layer1), - fluid.dygraph.base.to_variable(layer2)) - -属性 -:::::::::::: -.. py:attribute:: weight - -本层的可学习参数，类型为 ``Parameter`` - -.. py:attribute:: bias - -本层的可学习偏置，类型为 ``Parameter`` - - diff --git a/doc/paddle/api/paddle/nn/layer/common/CosineSimilarity_cn.rst b/doc/paddle/api/paddle/nn/layer/common/CosineSimilarity_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a11bb606ad14afd7c91871c10b618e5255209bde --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/CosineSimilarity_cn.rst @@ -0,0 +1,35 @@ +.. _cn_api_nn_CosineSimilarity: + +CosineSimilarity +------------------------------- +.. py:class:: paddle.nn.CosineSimilarity(axis=1, eps=1e-8) + +**CosineSimilarity** + +计算x1与x2沿axis维度的余弦相似度。 + +参数： + - **axis** (int) - 指定计算的维度，会在该维度上计算余弦相似度，默认值为1。 + - **eps** (float) - 很小的值，防止计算时分母为0，默认值为1e-8。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + np.random.seed(0) + x1 = np.random.rand(2,3) + x2 = np.random.rand(2,3) + x1 = paddle.to_tensor(x1) + x2 = paddle.to_tensor(x2) + + cos_sim_func = nn.CosineSimilarity(axis=0) + result = cos_sim_func(x1, x2) + print(result.numpy()) + # [0.99806249 0.9817672 0.94987036] diff --git a/doc/paddle/api/paddle/nn/Dropout_cn.rst b/doc/paddle/api/paddle/nn/layer/common/Dropout_cn.rst similarity index 100% rename from doc/paddle/api/paddle/nn/Dropout_cn.rst rename to doc/paddle/api/paddle/nn/layer/common/Dropout_cn.rst diff --git a/doc/paddle/api/paddle/nn/layer/common/Embedding_cn.rst b/doc/paddle/api/paddle/nn/layer/common/Embedding_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..985bf1c9eb834aa024ebab792a00b151328ef77a --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/Embedding_cn.rst @@ -0,0 +1,105 @@ +.. _cn_api_fluid_dygraph_Embedding: + +Embedding +------------------------------- + +.. py:class:: paddle.fluid.dygraph.Embedding(size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') + +:alias_main: paddle.nn.Embedding +:alias: paddle.nn.Embedding,paddle.nn.layer.Embedding,paddle.nn.layer.common.Embedding +:old_api: paddle.fluid.dygraph.Embedding + + + +嵌入层(Embedding Layer) + +该接口用于构建 ``Embedding`` 的一个可调用对象，具体用法参照 ``代码示例`` 。其根据input中的id信息从embedding矩阵中查询对应embedding信息，并会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。 + +输出的Tensor的shape是在输入Tensor shape的最后一维后面添加了emb_size的维度。 + +注：input中的id必须满足 ``0 =< id < size[0]``，否则程序会抛异常退出。 + + +:: + + Case 1: + + input是Tensor, 且padding_idx = -1 + input.data = [[1, 3], [2, 4], [4, 127]] + input.shape = [3, 2] + 若size = [128, 16] + 输出为Tensor: + out.shape = [3, 2, 16] + out.data = [[[0.129435295, 0.244512452, ..., 0.436322452], + [0.345421456, 0.524563927, ..., 0.144534654]], + + [[0.345249859, 0.124939536, ..., 0.194353745], + [0.945345345, 0.435394634, ..., 0.435345365]], + + [[0.945345345, 0.435394634, ..., 0.435345365], + [0.0, 0.0, ..., 0.0 ]]] # padding data + 输入的padding_idx小于0，则自动转换为padding_idx = -1 + 128 = 127, 对于输入id为127的词，进行padding处理。 + + Case 2: + + input是lod level 为1的LoDTensor, 且padding_idx = 0 + input.lod = [[2, 3]] + input.data = [[1], [3], [2], [4], [0]] + input.shape = [5, 1] + 若size = [128, 16] + 输出为LoDTensor: + out.lod = [[2, 3]] + out.shape = [5, 1, 16] + out.data = [[[0.129435295, 0.244512452, ..., 0.436322452]], + [[0.345421456, 0.524563927, ..., 0.144534654]], + [[0.345249859, 0.124939536, ..., 0.194353745]], + [[0.945345345, 0.435394634, ..., 0.435345365]], + [[0.0, 0.0, ..., 0.0 ]]] # padding data + 输入的padding_idx = 0，则对于输入id为0的词，进行padding处理。 + +参数： + - **size** (tuple|list) - embedding矩阵的维度。必须包含两个元素，第一个元素为vocab_size(词表大小), 第二个为emb_size（embedding层维度）。 + - **is_sparse** (bool) - 是否使用稀疏的更新方式，这个参数只会影响反向的梯度更新的性能，sparse更新速度更快，推荐使用稀疏更新的方式。但某些optimizer不支持sparse更新，比如 :ref:`cn_api_fluid_optimizer_AdadeltaOptimizer` 、 :ref:`cn_api_fluid_optimizer_AdamaxOptimizer` 、 :ref:`cn_api_fluid_optimizer_DecayedAdagradOptimizer` 、 :ref:`cn_api_fluid_optimizer_FtrlOptimizer` 、 :ref:`cn_api_fluid_optimizer_LambOptimizer` 、:ref:`cn_api_fluid_optimizer_LarsMomentumOptimizer` ，此时is_sparse必须为False。默认为False。 + - **is_distributed** (bool) - 是否使用分布式的方式存储embedding矩阵，仅在多机分布式cpu训练中使用。默认为False。 + - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx会被改成vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为None，不作处理，默认为None。 + - **param_attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为numpy数据格式，且保证本地词向量的shape和embedding的 ``size`` 参数一致，然后使用 :ref:`cn_api_fluid_initializer_NumpyArrayInitializer` 进行初始化，即可实现加载自定义或预训练的词向量。详细使用方法见代码示例2。 + - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32或float64，默认为float32。 + +返回：input映射后得到的Embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.dygraph.base as base + import numpy as np + + # 示例 1 + inp_word = np.array([[2, 3, 5], [4, 2, 1]]).astype('int64') + inp_word.shape # [2, 3] + dict_size = 20 + with fluid.dygraph.guard(): + emb = fluid.dygraph.Embedding( + size=[dict_size, 32], + param_attr='emb.w', + is_sparse=False) + static_rlt3 = emb(base.to_variable(inp_word)) + static_rlt3.shape # [2, 3, 32] + + # 示例 2: 加载用户自定义或预训练的词向量 + weight_data = np.random.random(size=(128, 100)) # numpy格式的词向量数据 + w_param_attrs = fluid.ParamAttr( + name="emb_weight", + learning_rate=0.5, + initializer=fluid.initializer.NumpyArrayInitializer(weight_data), + trainable=True) + with fluid.dygraph.guard(): + emb = fluid.dygraph.Embedding( + size=[128, 100], + param_attr= w_param_attrs, + is_sparse=False) + static_rlt3 = emb(base.to_variable(inp_word)) + diff --git a/doc/paddle/api/paddle/nn/layer/common/ReflectionPad1d_cn.rst b/doc/paddle/api/paddle/nn/layer/common/ReflectionPad1d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..bba4b39464fe5e8bdb4ee0626d912ad8f9e2e858 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/ReflectionPad1d_cn.rst @@ -0,0 +1,35 @@ +.. _cn_api_nn_ReflectionPad1d: + +ReflectionPad1d +------------------------------- +.. py:class:: paddle.nn.ReflectionPad1d(padding, data_format="NCL", name=None) + +**ReflectionPad1d** + +按照 padding 对输入 以reflection模式进行 ``pad``，即填充以输入边界值为轴的映射 。 + +参数： + - **padding** (Tensor | List[int32]) - 填充大小。pad的格式为[pad_left, pad_right]。 + - **data_format** (str) - 指定input的format，可为 `'NCL'` 或者 `'NLC'`，默认值为`'NCL'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + input_shape = (1, 2, 3) + pad = [1, 2] + data = np.arange(np.prod(input_shape), dtype=np.float32).reshape(input_shape) + 1 + my_pad = nn.ReflectionPad1d(padding=pad) + data = paddle.to_tensor(data) + result = my_pad(data) + print(result.numpy()) + # [[[2. 1. 2. 3. 2. 1.] + # [5. 4. 5. 6. 5. 4.]]] diff --git a/doc/paddle/api/paddle/nn/layer/common/ReflectionPad2d_cn.rst b/doc/paddle/api/paddle/nn/layer/common/ReflectionPad2d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..35fdb4bc0f2af5d55629ba5cb9f101dd8f3f2150 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/ReflectionPad2d_cn.rst @@ -0,0 +1,40 @@ +.. _cn_api_nn_ReflectionPad2d: + +ReflectionPad2d +------------------------------- +.. py:class:: paddle.nn.ReflectionPad2d(padding, data_format="NCHW", name=None) + +**ReflectionPad2d** + +按照 padding 对输入 以reflection模式进行 ``pad``，即填充以输入边界值为轴的映射 。 + +参数： + - **padding** (Tensor | List[int32]) - 填充大小。pad的格式为[pad_left, pad_right, pad_top, pad_bottom]。。 + - **data_format** (str) - 指定input的format，可为 `'NCHW'` 或者 `'NHWC'`，默认值为`'NCHW'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + input_shape = (1, 1, 4, 3) + pad = [1, 0, 1, 2] + data = np.arange(np.prod(input_shape), dtype=np.float32).reshape(input_shape) + 1 + my_pad = nn.ReflectionPad2d(padding=pad) + data = paddle.to_tensor(data) + result = my_pad(data) + print(result.numpy()) + # [[[[ 5. 4. 5. 6.] + # [ 2. 1. 2. 3.] + # [ 5. 4. 5. 6.] + # [ 8. 7. 8. 9.] + # [11. 10. 11. 12.] + # [ 8. 7. 8. 9.] + # [ 5. 4. 5. 6.]]]] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/layer/common/ReplicationPad1d_cn.rst b/doc/paddle/api/paddle/nn/layer/common/ReplicationPad1d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..aade886104421dcec986096a6288846f54828576 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/ReplicationPad1d_cn.rst @@ -0,0 +1,35 @@ +.. _cn_api_nn_ReplicationPad1d: + +ReplicationPad1d +------------------------------- +.. py:class:: paddle.nn.ReplicationPad1d(padding, data_format="NCL", name=None) + +**ReplicationPad1d** + +按照 padding 对输入 以replicate模式进行 ``pad``，即填充输入的边界值。 + +参数： + - **padding** (Tensor | List[int32]) - 填充大小。pad的格式为[pad_left, pad_right]。 + - **data_format** (str) - 指定input的format，可为 `'NCL'` 或者 `'NLC'`，默认值为`'NCL'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + input_shape = (1, 2, 3) + pad = [1, 2] + data = np.arange(np.prod(input_shape), dtype=np.float32).reshape(input_shape) + 1 + my_pad = nn.ReplicationPad1d(padding=pad) + data = paddle.to_tensor(data) + result = my_pad(data) + print(result.numpy()) + # [[[1. 1. 2. 3. 3. 3.] + # [4. 4. 5. 6. 6. 6.]]] diff --git a/doc/paddle/api/paddle/nn/layer/common/ReplicationPad2d_cn.rst b/doc/paddle/api/paddle/nn/layer/common/ReplicationPad2d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..97b41a220b9ccfe3813cdcfd26029126d4b4be22 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/ReplicationPad2d_cn.rst @@ -0,0 +1,38 @@ +.. _cn_api_nn_ReplicationPad2d: + +ReplicationPad2d +------------------------------- +.. py:class:: paddle.nn.ReplicationPad2d(padding, data_format="NCHW", name=None) + +**ReplicationPad2d** + +按照 padding 对输入 以replicate模式进行 ``pad``，即填充输入的边界值。 + +参数： + - **padding** (Tensor | List[int32]) - 填充大小。pad的格式为[pad_left, pad_right, pad_top, pad_bottom]。 + - **data_format** (str) - 指定input的format，可为 `'NCHW'` 或者 `'NHWC'`，默认值为`'NCHW'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + input_shape = (1, 1, 2, 3) + pad = [1, 0, 1, 2] + data = np.arange(np.prod(input_shape), dtype=np.float32).reshape(input_shape) + 1 + my_pad = nn.ReplicationPad2d(padding=pad) + data = paddle.to_tensor(data) + result = my_pad(data) + print(result.numpy()) + # [[[[1. 1. 2. 3.] + # [1. 1. 2. 3.] + # [4. 4. 5. 6.] + # [4. 4. 5. 6.] + # [4. 4. 5. 6.]]]] diff --git a/doc/paddle/api/paddle/nn/layer/common/ReplicationPad3d_cn.rst b/doc/paddle/api/paddle/nn/layer/common/ReplicationPad3d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..4d379c21297d0602c97cfeba3f81e06585cc1026 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/ReplicationPad3d_cn.rst @@ -0,0 +1,38 @@ +.. _cn_api_nn_ReplicationPad3d: + +ReplicationPad3d +------------------------------- +.. py:class:: paddle.nn.ReplicationPad3d(padding, data_format="NCDHW", name=None) + +**ReplicationPad3d** + +按照 padding 对输入 以replicate模式进行 ``pad``，即填充输入的边界值。 + +参数： + - **padding** (Tensor | List[int32]) - 填充大小。pad的格式为[pad_left, pad_right, pad_top, pad_bottom, pad_front, pad_back]。 + - **data_format** (str) - 指定input的format，可为 `'NCDHW'` 或者 `'NDHWC'`，默认值为`'NCDHW'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + input_shape = (1, 1, 1, 2, 3) + pad = [1, 0, 1, 2, 0, 0] + data = np.arange(np.prod(input_shape), dtype=np.float32).reshape(input_shape) + 1 + my_pad = nn.ReplicationPad3d(padding=pad) + data = paddle.to_tensor(data) + result = my_pad(data) + print(result.numpy()) + # [[[[[1. 1. 2. 3.] + # [1. 1. 2. 3.] + # [4. 4. 5. 6.] + # [4. 4. 5. 6.] + # [4. 4. 5. 6.]]]]] diff --git a/doc/paddle/api/paddle/nn/layer/common/ZeroPad2d_cn.rst b/doc/paddle/api/paddle/nn/layer/common/ZeroPad2d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..ed6a69b86fdb93f4172a14d638abd08022910e1b --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/common/ZeroPad2d_cn.rst @@ -0,0 +1,38 @@ +.. _cn_api_nn_ZeroPad2d: + +ZeroPad2d +------------------------------- +.. py:class:: paddle.nn.ZeroPad2d(padding, data_format="NCHW", name=None) + +**ZeroPad2d** + +按照 padding 对输入填充固定值0。 + +参数： + - **padding** (Tensor | List[int32]) - 填充大小。pad的格式为[pad_left, pad_right, pad_top, pad_bottom]。 + - **data_format** (str) - 指定input的format，可为 `'NCHW'` 或者 `'NHWC'`，默认值为`'NCHW'`。 + - **name** (str, 可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 + +返回：无 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + input_shape = (1, 1, 2, 3) + pad = [1, 0, 1, 2] + data = np.arange(np.prod(input_shape), dtype=np.float32).reshape(input_shape) + 1 + my_pad = nn.ZeroPad2d(padding=pad) + data = paddle.to_tensor(data) + result = my_pad(data) + print(result.numpy()) + # [[[[0. 0. 0. 0.] + # [0. 1. 2. 3.] + # [0. 4. 5. 6.] + # [0. 0. 0. 0.] + # [0. 0. 0. 0.]]]] diff --git a/doc/paddle/api/paddle/nn/layer/distance/PairwiseDistance_cn.rst b/doc/paddle/api/paddle/nn/layer/distance/PairwiseDistance_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..94e1d04bbe23d9c5e49277902c9fd206a6e02c12 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/distance/PairwiseDistance_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_nn_PairwiseDistance: + +PairwiseDistance +------------------------------- + +.. py:class:: paddle.nn.PairwiseDistance(p=2., epsilon=1e-6, keepdim=False, name=None) + +该OP计算两个向量（输入 ``x``、``y`` ）之间pairwise的距离。该距离通过p范数计算： + + .. math:: + + \Vert x \Vert _p = \left( \sum_{i=1}^n \vert x_i \vert ^ p \right ) ^ {1/p}. + +参数 +:::::::: + - **p** （float，可选）- 指定p阶的范数。默认值为2。 + - **epsilon** （float，可选）- 添加到分母的一个很小值，避免发生除零错误。默认值为1e-6。 + - **keepdim** （bool，可选）- 是否保留输出张量减少的维度。输出结果相对于 ``|x-y|`` 的结果减少一维，除非 :attr:`keepdim` 为True，默认值为False。 + - **name** （str，可选） - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +形状 +:::::::: + - **x** (Tensor) - :math:`(N, D)` ，其中D是向量的维度，数据类型为float32或float64。 + - **y** (Tensor) - :math:`(N, D)` ，与 ``x`` 的形状、数据类型相同。 + - **output** (Tensor) - :math:`(N)` ，如果 :attr:`keepdim` 为True，则形状为 :math:`(N, 1)` 。数据类型与 ``x``、 ``y`` 相同。 + +代码示例 +:::::::: + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + x_np = np.array([[1., 3.], [3., 5.]]).astype(np.float64) + y_np = np.array([[5., 6.], [7., 8.]]).astype(np.float64) + x = paddle.to_variable(x_np) + y = paddle.to_variable(y_np) + dist = paddle.nn.PairwiseDistance() + distance = dist(x, y) + print(distance.numpy()) # [5. 5.] + diff --git a/doc/paddle/api/paddle/nn/layer/loss/BCELoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/BCELoss_cn.rst index 78cd4fb635e65cfb216a37e83679650e0f88197d..0231b6eb5a19db9448376be8f7106dfe083604b7 100644 --- a/doc/paddle/api/paddle/nn/layer/loss/BCELoss_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/loss/BCELoss_cn.rst @@ -3,9 +3,9 @@ BCELoss ------------------------------- -.. py:function:: paddle.nn.BCELoss(input, label, weight=None, reduction='mean') +.. py:class:: paddle.nn.BCELoss(weight=None, reduction='mean', name=None) -该接口用于创建一个BCELoss的可调用类，用于计算输入和标签之间的二值交叉熵损失值。二值交叉熵损失函数公式如下： +该接口用于创建一个BCELoss的可调用类，用于计算输入 ``input`` 和标签 ``label`` 之间的二值交叉熵损失值。二值交叉熵损失函数公式如下： 当 `weight` 不为空时，公式为： @@ -17,12 +17,9 @@ BCELoss .. math:: Out = -1 * (label * log(input) + (1 - label) * log(1 - input)) -当 `reduction` 为 `none` 时，最终的输出结果为： +当 `reduction` 为 `none` 时，直接返回最原始的 `Out` 结果。 -.. math:: - Out = Out - -当 `reduction` 为 `sum` 时，最终的输出结果为： +当 `reduction` 为 `mean` 时，最终的输出结果为： .. math:: Out = MEAN(Out) @@ -33,47 +30,36 @@ BCELoss Out = SUM(Out) -**注意：输入数据一般是 `fluid.layers.sigmoid` 的输出。因为是二分类，所以标签值应该是0或者1。 +.. note:: + 输入数据 ``input`` 一般是 ``sigmoid`` 的输出。因为是二分类，所以标签值 ``label`` 应该是0或者1。 -输入input和标签label的维度是[N, *], 其中N是batch_size， `*` 是任意其他维度。 -如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 [N, *], 与输入input的形状相同。 -如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 [1]。 +参数 +::::::::: + - **weight** (Tensor，可选) - 手动指定每个batch二值交叉熵的权重，如果指定的话，维度必须是一个batch的数据的维度。数据类型是float32, float64。默认值是：None。 + - **reduction** (str，可选) - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `BCELoss` 的均值；设置为 ``'sum'`` 时，计算 `BCELoss` 的总和；设置为 ``'none'`` 时，则返回bce_loss。 + - **name** (str，可选) - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 -参数： - - **weight(Variable, optional)**：- 手动指定每个batch二值交叉熵的权重，如果指定的话，维度必须是一个batch的数据的维度。数据类型是float32, float64。默认是：None。 - - **reduction(str, optional)**：- 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `BCELoss` 的均值；设置为 ``'sum'`` 时，计算 `BCELoss` 的总和；设置为 ``'none'`` 时，则返回BCELoss。 +形状 +::::::::: + - **input** (Tensor) - :math:`(N, *)` , 其中N是batch_size， `*` 是任意其他维度。输入数据 ``input`` 一般是 ``sigmoid`` 的输出。数据类型是float32、float64。 + - **label** (Tensor) - :math:`(N, *)` ，标签 ``label`` 的维度、数据类型与输入 ``input`` 相同。 + - **output** (Tensor) - 输出的Tensor。如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 :math:`(N, *)` , 与输入 ``input`` 的形状相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 :math:`[1]` 。 -返回：返回计算BCELoss的可调用对象。 +返回 +::::::::: + 返回计算BCELoss的可调用对象。 -**代码示例** +代码示例 +:::::::::: .. code-block:: python - # declarative mode - import paddle.fluid as fluid - import numpy as np import paddle - input = fluid.data(name="input", shape=[3, 1], dtype='float32') - label = fluid.data(name="label", shape=[3, 1], dtype='float32') + + paddle.disable_static() + input = paddle.to_tensor([0.5, 0.6, 0.7], dtype='float32') + label = paddle.to_tensor([1.0, 0.0, 1.0], dtype='float32') bce_loss = paddle.nn.loss.BCELoss() output = bce_loss(input, label) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - - input_data = np.array([0.5, 0.6, 0.7]).astype("float32") - label_data = np.array([1.0, 0.0, 1.0]).astype("float32") - output_data = exe.run(fluid.default_main_program(), - feed={"input":input_data, "label":label_data}, - fetch_list=[output], - return_numpy=True) - - print(output_data) # [array([0.65537095], dtype=float32)] - - # imperative mode - import paddle.fluid.dygraph as dg - with dg.guard(place) as g: - input = dg.to_variable(input_data) - label = dg.to_variable(label_data) - output = bce_loss(input, label) - print(output.numpy()) # [0.65537095] + print(output.numpy()) # [0.65537095] + diff --git a/doc/paddle/api/paddle/nn/layer/loss/BCEWithLogitsLoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/BCEWithLogitsLoss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..aef2aae152051cadf3ffca5f19568d8e68f73c3b --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/loss/BCEWithLogitsLoss_cn.rst @@ -0,0 +1,64 @@ +.. _cn_api_paddle_nn_BCEWithLogitsLoss: + +BCEWithLogitsLoss +------------------------------- + +.. py:class:: paddle.nn.BCEWithLogitsLoss(weight=None, reduction='mean', pos_weight=None, name=None) + +该OP可创建一个BCEWithLogitsLoss的可调用类，计算输入 `logit` 和标签 `label` 间的 `binary cross entropy with logits loss` 损失。 + +该OP结合了 `sigmoid` 操作和 :ref:`api_nn_loss_BCELoss` 操作。同时，我们也可以认为该OP是 ``sigmoid_cross_entrop_with_logits`` 和一些 `reduce` 操作的组合。 + +在每个类别独立的分类任务中，该OP可以计算按元素的概率误差。可以将其视为预测数据点的标签，其中标签不是互斥的。例如，一篇新闻文章可以同时关于政治，科技，体育或者同时不包含这些内容。 + +首先，该OP可通过下式计算损失函数： + +.. math:: + Out = -Labels * \log(\sigma(Logit)) - (1 - Labels) * \log(1 - \sigma(Logit)) + +其中 :math:`\sigma(Logit) = \frac{1}{1 + e^{-Logit}}` ， 代入上方计算公式中: + +.. math:: + Out = Logit - Logit * Labels + \log(1 + e^{-Logit}) + +为了计算稳定性，防止当 :math:`Logit<0` 时， :math:`e^{-Logit}` 溢出，loss将采用以下公式计算: + +.. math:: + Out = \max(Logit, 0) - Logit * Labels + \log(1 + e^{-\|Logit\|}) + +然后，当 ``weight`` or ``pos_weight`` 不为None的时候，该算子会在输出Out上乘以相应的权重。张量 ``weight`` 给Batch中的每一条数据赋予不同权重，张量 ``pos_weight`` 给每一类的正例添加相应的权重。 + +最后，该算子会添加 `reduce` 操作到前面的输出Out上。当 `reduction` 为 `none` 时，直接返回最原始的 `Out` 结果。当 `reduction` 为 `mean` 时，返回输出的均值 :math:`Out = MEAN(Out)` 。当 `reduction` 为 `sum` 时，返回输出的求和 :math:`Out = SUM(Out)` 。 + +**注意: 因为是二分类任务，所以标签值应该是0或者1。 + +参数 +::::::::: + - **weight** (Tensor，可选) - 手动指定每个batch二值交叉熵的权重，如果指定的话，维度必须是一个batch的数据的维度。数据类型是float32, float64。默认值是：None。 + - **reduction** (str，可选) - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `BCELoss` 的均值；设置为 ``'sum'`` 时，计算 `BCELoss` 的总和；设置为 ``'none'`` 时，则返回原始loss。 + - **pos_weight** (Tensor，可选) - 手动指定正类的权重，必须是与类别数相等长度的向量。数据类型是float32, float64。默认值是：None。 + - **name** (str，可选) - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +形状 +::::::::: + - **logit** (Tensor) - :math:`[N, *]` , 其中N是batch_size， `*` 是任意其他维度。输入数据 ``logit`` 一般是线性层的输出，不需要经过 ``sigmoid`` 层。数据类型是float32、float64。 + - **label** (Tensor) - :math:`[N, *]` ，标签 ``label`` 的维度、数据类型与输入 ``logit`` 相同。 + - **output** (Tensor) - 输出的Tensor。如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 :math:`[N, *]` , 与输入 ``input`` 的形状相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 :math:`[1]` 。 + +返回 +::::::::: + 返回计算BCEWithLogitsLoss的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + paddle.disable_static() + logit = paddle.to_tensor([5.0, 1.0, 3.0], dtype="float32") + label = paddle.to_tensor([1.0, 0.0, 1.0], dtype="float32") + bce_logit_loss = paddle.nn.BCEWithLogitsLoss() + output = bce_logit_loss(logit, label) + print(output.numpy()) # [0.45618808] + diff --git a/doc/paddle/api/paddle/nn/layer/loss/CTCLoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/CTCLoss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a2ad0c28a4058d8cbdfc447b9f890e0ce9d24185 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/loss/CTCLoss_cn.rst @@ -0,0 +1,78 @@ +CTCLoss +------------------------------- + +.. py:class:: paddle.nn.loss.CTCLoss(blank=0, reduction='mean') + +该接口用于计算 CTC loss。该接口的底层调用了第三方 baidu-research::warp-ctc 的实现。 +也可以叫做 softmax with CTC，因为 Warp-CTC 库中插入了 softmax 激活函数来对输入的值进行归一化。 + +参数 +::::::::: + - **blank** (int，可选): - 空格标记的 ID 值，其取值范围为 [0，num_classes+1) 。数据类型支持int32。默认值为0。 + - **reduction** (string，可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。设置为 ``'mean'`` 时，对 loss 值除以 label_lengths，并返回所得商的均值；设置为 ``'sum'`` 时，返回 loss 值的总和；设置为 ``'none'`` 时，则直接返回输出的 loss 值。默认值为 ``'mean'``。 + +形状 +::::::::: + - **log_probs** (Tensor): - 经过 padding 的概率序列，其 shape 必须是 [max_logit_length, batch_size, num_classes + 1]。其中 max_logit_length 是最长输入序列的长度。该输入不需要经过 softmax 操作，因为该 OP 的内部对 input 做了 softmax 操作。数据类型仅支持float32。 + - **labels** (Tensor): - 经过 padding 的标签序列，其 shape 为 [batch_size, max_label_length]，其中 max_label_length 是最长的 label 序列的长度。数据类型支持int32。 + - **input_lengths** (Tensor): - 表示输入 ``log_probs`` 数据中每个序列的长度，shape为 [batch_size] 。数据类型支持int64。 + - **label_lengths** (Tensor): - 表示 label 中每个序列的长度，shape为 [batch_size] 。数据类型支持int64。 + +返回 +::::::::: +``Tensor``，输入 ``log_probs`` 和标签 ``labels`` 间的 `ctc loss`。如果 :attr:`reduction` 是 ``'none'``，则输出 loss 的维度为 [batch_size]。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。数据类型与输入 ``log_probs`` 一致。 + +代码示例 +::::::::: + +.. code-block:: python + + # declarative mode + import numpy as np + import paddle + + # length of the longest logit sequence + max_seq_length = 4 + #length of the longest label sequence + max_label_length = 3 + # number of logit sequences + batch_size = 2 + # class num + class_num = 3 + + np.random.seed(1) + log_probs = np.array([[[4.17021990e-01, 7.20324516e-01, 1.14374816e-04], + [3.02332580e-01, 1.46755889e-01, 9.23385918e-02]], + + [[1.86260208e-01, 3.45560730e-01, 3.96767467e-01], + [5.38816750e-01, 4.19194520e-01, 6.85219526e-01]], + + [[2.04452246e-01, 8.78117442e-01, 2.73875929e-02], + [6.70467496e-01, 4.17304814e-01, 5.58689833e-01]], + + [[1.40386939e-01, 1.98101491e-01, 8.00744593e-01], + [9.68261600e-01, 3.13424170e-01, 6.92322612e-01]], + + [[8.76389146e-01, 8.94606650e-01, 8.50442126e-02], + [3.90547849e-02, 1.69830427e-01, 8.78142476e-01]]]).astype("float32") + labels = np.array([[1, 2, 2], + [1, 2, 2]]).astype("int32") + input_lengths = np.array([5, 5]).astype("int64") + label_lengths = np.array([3, 3]).astype("int64") + + paddle.disable_static() + log_probs = paddle.to_tensor(log_probs) + labels = paddle.to_tensor(labels) + input_lengths = paddle.to_tensor(input_lengths) + label_lengths = paddle.to_tensor(label_lengths) + + loss = paddle.nn.CTCLoss(blank=0, reduction='none')(log_probs, labels, + input_lengths, + label_lengths) + print(loss.numpy()) #[3.9179852 2.9076521] + + loss = paddle.nn.CTCLoss(blank=0, reduction='mean')(log_probs, labels, + input_lengths, + label_lengths) + print(loss.numpy()) #[1.1376063] + diff --git a/doc/paddle/api/paddle/nn/layer/loss/CrossEntropyLoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/CrossEntropyLoss_cn.rst index 5e85d3a50dba92772a068ee8dc0e0beaaf3ddc73..0535e8690f6902f24fb31e39fa06d61bf4c88117 100644 --- a/doc/paddle/api/paddle/nn/layer/loss/CrossEntropyLoss_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/loss/CrossEntropyLoss_cn.rst @@ -1,9 +1,11 @@ +.. _cn_api_nn_loss_CrossEntropyLoss: + CrossEntropyLoss ------------------------------- -.. py:function:: paddle.nn.loss.CrossEntropyLoss(weight=None, reduction='mean', ignore_index=-100) +.. py:function:: paddle.nn.loss.CrossEntropyLoss(weight=None, ignore_index=-100, reduction='mean') -该OP计算输入input和标签label间的交叉熵损失 ，它结合了`LogSoftmax` 和 `NLLLoss` 的OP计算，可用于训练一个 `n` 类分类器。 +该OP计算输入input和标签label间的交叉熵损失 ，它结合了 `LogSoftmax` 和 `NLLLoss` 的OP计算，可用于训练一个 `n` 类分类器。 如果提供 `weight` 参数的话，它是一个 `1-D` 的tensor, 每个值对应每个类别的权重。 该损失函数的数学计算公式如下： @@ -19,48 +21,34 @@ CrossEntropyLoss \log\left(\sum_{i=0}^{K}\exp(\text{input}_i)\right)), j = 1,..., K -参数： - - **input** (Variable): - 输入 `Tensor`，数据类型为float32或float64。其形状为 :math:`[N, C]` , 其中 `C` 为类别数。对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_k]`，k >= 1。 - - **label** (Variable): - 输入input对应的标签值，数据类型为int64。其形状为 :math:`[N]`，每个元素符合条件：0 <= label[i] <= C-1。对于多维度的情形下，它的形状为 :math:`[N, d_1, d_2, ..., d_k]`，k >= 1。 - - **weight** (Variable, 可选): - 指定每个类别的权重。其默认为 `None` 。如果提供该参数的话，维度必须为 `C`（类别数）。数据类型为float32或float64。 - - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，数据类型为string，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算 `mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。 +参数 +::::::::: + - **weight** (Tensor, 可选): - 指定每个类别的权重。其默认为 `None` 。如果提供该参数的话，维度必须为 `C` （类别数）。数据类型为float32或float64。 - **ignore_index** (int64, 可选): - 指定一个忽略的标签值，此标签值不参与计算。默认值为-100。数据类型为int64。 + - **reduction** (str, 可选): - 指定应用于输出结果的计算方式，数据类型为string，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算 `mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。 -返回：返回计算 `CrossEntropyLoss` 交叉熵后的损失值。 +形状 +::::::::: + - **input** (Tensor): - 输入 `Tensor` ，数据类型为float32或float64。其形状为 :math:`[N, C]` , 其中 `C` 为类别数。对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_k]` ，k >= 1。 + - **label** (Tensor): - 输入input对应的标签值，数据类型为int64。其形状为 :math:`[N]` ，每个元素符合条件：0 <= label[i] <= C-1。对于多维度的情形下，它的形状为 :math:`[N, d_1, d_2, ..., d_k]` ，k >= 1。 + - **output** (Tensor): - 计算 `CrossEntropyLoss` 交叉熵后的损失值。 -返回类型：Variable -**代码示例** +代码示例 +::::::::: .. code-block:: python - # declarative mode import paddle - import paddle.fluid as fluid import numpy as np - input = fluid.data(name='input', shape=[5, 100], dtype='float64') - label = fluid.data(name='label', shape=[5], dtype='int64') - weight = fluid.data(name='weight', shape=[100], dtype='float64') - ce_loss = paddle.nn.loss.CrossEntropyLoss(weight=weight, reduction='mean') - output = ce_loss(input, label) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) + paddle.disable_static() input_data = np.random.random([5, 100]).astype("float64") label_data = np.random.randint(0, 100, size=(5)).astype(np.int64) weight_data = np.random.random([100]).astype("float64") - output = exe.run(fluid.default_main_program(), - feed={"input": input_data, "label": label_data,"weight": weight_data}, - fetch_list=[output], - return_numpy=True) - print(output) - # imperative mode - import paddle.fluid.dygraph as dg - with dg.guard(place) as g: - input = dg.to_variable(input_data) - label = dg.to_variable(label_data) - weight = dg.to_variable(weight_data) - ce_loss = paddle.nn.loss.CrossEntropyLoss(weight=weight, reduction='mean') - output = ce_loss(input, label) - print(output.numpy()) + input = paddle.to_tensor(input_data) + label = paddle.to_tensor(label_data) + weight = paddle.to_tensor(weight_data) + ce_loss = paddle.nn.loss.CrossEntropyLoss(weight=weight, reduction='mean') + output = ce_loss(input, label) + print(output.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/loss/L1Loss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/L1Loss_cn.rst index c2cc4e38e6ffbb6322dce8ca29656b49cd12705a..f5a41b3a80888c195da84a470a45c87d70b08ed3 100644 --- a/doc/paddle/api/paddle/nn/layer/loss/L1Loss_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/loss/L1Loss_cn.rst @@ -1,7 +1,7 @@ L1Loss ------------------------------- -.. py:function:: paddle.nn.loss.L1Loss(reduction='mean') +.. py:class:: paddle.nn.loss.L1Loss(reduction='mean', name=None) 该接口用于创建一个L1Loss的可调用类，L1Loss计算输入input和标签label间的 `L1 loss` 损失。 @@ -10,58 +10,57 @@ L1Loss 当 `reduction` 设置为 ``'none'`` 时， .. math:: - Out = |input - label| + Out = \lvert input - label\rvert 当 `reduction` 设置为 ``'mean'`` 时， .. math:: - Out = MEAN(|input - label|) + Out = MEAN(\lvert input - label\rvert) 当 `reduction` 设置为 ``'sum'`` 时， .. math:: - Out = SUM(|input - label|) + Out = SUM(\lvert input - label\rvert) -输入input和标签label的维度是[N, *], 其中N是batch_size， `*` 是任意其他维度。 -如果 :attr:`reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入input相同。 -如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 -参数： - - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `L1Loss` 的均值；设置为 ``'sum'`` 时，计算 `L1Loss` 的总和；设置为 ``'none'`` 时，则返回L1Loss。数据类型为string。 +参数 +::::::::: + - **reduction** (str, 可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `L1Loss` 的均值；设置为 ``'sum'`` 时，计算 `L1Loss` 的总和；设置为 ``'none'`` 时，则返回 `L1Loss`。 + - **name** (str，可选): - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回：返回计算L1Loss的可调用对象。 +形状 +::::::::: + - **input** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64、int32、int64。 + - **label** (Tensor): - 标签，维度是[N, *], 与 ``input`` 相同。数据类型为：float32、float64、int32、int64。 + - **output** (Tensor): - 输入 ``input`` 和标签 ``label`` 间的 `L1 loss` 损失。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``input`` 相同。如果 `reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 -**代码示例** +代码示例 +::::::::: .. code-block:: python - # declarative mode - import paddle.fluid as fluid import numpy as np import paddle - input = fluid.data(name="input", shape=[1]) - label = fluid.data(name="label", shape=[1]) - l1_loss = paddle.nn.loss.L1Loss(reduction='mean') - output = l1_loss(input,label) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - - input_data = np.array([1.5]).astype("float32") - label_data = np.array([1.7]).astype("float32") - output_data = exe.run(fluid.default_main_program(), - feed={"input":input_data, "label":label_data}, - fetch_list=[output], - return_numpy=True) - - print(output_data) # [array([0.2], dtype=float32)] - - # imperative mode - import paddle.fluid.dygraph as dg - with dg.guard(place) as g: - input = dg.to_variable(input_data) - label = dg.to_variable(label_data) - l1_loss = paddle.nn.loss.L1Loss(reduction='mean') - output = l1_loss(input,label) - print(output.numpy()) # [0.2] + + paddle.disable_static() + input_data = np.array([[1.5, 0.8], [0.2, 1.3]]).astype("float32") + label_data = np.array([[1.7, 1], [0.4, 0.5]]).astype("float32") + input = paddle.to_variable(input_data) + label = paddle.to_variable(label_data) + + l1_loss = paddle.nn.loss.L1Loss() + output = l1_loss(input, label) + print(output.numpy()) + # [0.35] + + l1_loss = paddle.nn.loss.L1Loss(reduction='sum') + output = l1_loss(input, label) + print(output.numpy()) + # [1.4] + + l1_loss = paddle.nn.loss.L1Loss(reduction='none') + output = l1_loss(input, label) + print(output.numpy()) + # [[0.20000005 0.19999999] + # [0.2 0.79999995]] diff --git a/doc/paddle/api/paddle/nn/layer/loss/MSELoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/MSELoss_cn.rst index 4dfa7bfba423c2a12005da89c07fe562442b6a5a..3ddeca33f5034d569fdf9362ceb83e05f1b35943 100644 --- a/doc/paddle/api/paddle/nn/layer/loss/MSELoss_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/loss/MSELoss_cn.rst @@ -1,7 +1,7 @@ MSELoss ------------------------------- -.. py:function:: paddle.nn.loss.MSELoss(input,label) +.. py:function:: paddle.nn.loss.MSELoss(reduction='mean') 该OP用于计算预测值和目标值的均方差误差。 @@ -23,13 +23,15 @@ MSELoss Out = \operatorname{sum}((input - label)^2) 参数： - - **input** (Variable) - 预测值，维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。 - - **label** (Variable) - 目标值，维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。 - **reduction** (str, 可选) - 约简方式，可以是 'none' | 'mean' | 'sum'。设为'none'时不使用约简，设为'mean'时返回loss的均值，设为'sum'时返回loss的和。 -返回：预测值和目标值的均方差 +形状: + - **input** (Tensor) - 预测值，维度为 :math:`[N_1, N_2, ..., N_k]` 的多维Tensor。数据类型为float32或float64。 + - **label** (Tensor) - 目标值，维度为 :math:`[N_1, N_2, ..., N_k]` 的多维Tensor。数据类型为float32或float64。 + + +返回：变量（Tensor）, 预测值和目标值的均方差, 数值类型与输入相同 -返回类型：变量（Variable） **代码示例**： @@ -37,32 +39,32 @@ MSELoss import numpy as np import paddle - from paddle import fluid - import paddle.fluid.dygraph as dg + + # static graph mode + paddle.enable_static() mse_loss = paddle.nn.loss.MSELoss() - input = fluid.data(name="input", shape=[1]) - label = fluid.data(name="label", shape=[1]) - place = fluid.CPUPlace() + input = paddle.data(name="input", shape=[1]) + label = paddle.data(name="label", shape=[1]) + place = paddle.CPUPlace() input_data = np.array([1.5]).astype("float32") label_data = np.array([1.7]).astype("float32") - # declarative mode output = mse_loss(input,label) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) + exe = paddle.static.Executor(place) + exe.run(paddle.static.default_startup_program()) output_data = exe.run( - fluid.default_main_program(), + paddle.static.default_main_program(), feed={"input":input_data, "label":label_data}, fetch_list=[output], return_numpy=True) print(output_data) # [array([0.04000002], dtype=float32)] - # imperative mode - with dg.guard(place) as g: - input = dg.to_variable(input_data) - label = dg.to_variable(label_data) - output = mse_loss(input, label) - print(output.numpy()) - # [0.04000002] + # dynamic graph mode + paddle.disable_static() + input = paddle.to_variable(input_data) + label = paddle.to_variable(label_data) + output = mse_loss(input, label) + print(output.numpy()) + # [0.04000002] diff --git a/doc/paddle/api/paddle/nn/layer/loss/MarginRankingLoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/MarginRankingLoss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..ab7cd2175d25e3f3e724c3417e1b02db2158a895 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/loss/MarginRankingLoss_cn.rst @@ -0,0 +1,60 @@ +.. _cn_api_nn_loss_MarginRankingLoss: + +MarginRankingLoss +------------------------------- + +.. py:class:: paddle.nn.loss.MarginRankingLoss(margin=0.0, reduction='mean', name=None) + +该接口用于创建一个 ``MarginRankingLoss`` 的可调用类，计算输入input，other 和 标签label间的 `margin rank loss` 损失。 + +该损失函数的数学计算公式如下： + + .. math:: + margin\_rank\_loss = max(0, -label * (input - other) + margin) + +当 `reduction` 设置为 ``'mean'`` 时， + + .. math:: + Out = MEAN(margin\_rank\_loss) + +当 `reduction` 设置为 ``'sum'`` 时， + + .. math:: + Out = SUM(margin\_rank\_loss) + +当 `reduction` 设置为 ``'none'`` 时，直接返回最原始的 `margin_rank_loss` 。 + +参数 +:::::::: + - **margin** （float，可选）： - 用于加和的margin值，默认值为0。 + - **reduction** （string，可选）： - 指定应用于输出结果的计算方式，可选值有: ``'none'`` 、 ``'mean'`` 、 ``'sum'`` 。如果设置为 ``'none'`` ，则直接返回 最原始的 ``margin_rank_loss`` 。如果设置为 ``'sum'`` ，则返回 ``margin_rank_loss`` 的总和。如果设置为 ``'mean'`` ，则返回 ``margin_rank_loss`` 的平均值。默认值为 ``'none'`` 。 + - **name** （str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状 +:::::::: + - **input** - N-D Tensor, 维度是[N，*] 其中N 是batch size，`*` 是任意数量的额外维度，数据类型为float32或float64。 + - **other** - 与 ``input`` 的形状、数据类型相同。 + - **label** - 与 ``input`` 的形状、数据类型相同。 + - **output** - 如果 :attr:`reduction` 为 ``'sum'`` 或者是 ``'mean'`` ，则形状为 :math:`[1]` ，否则shape和输入 `input` 保持一致 。数据类型与 ``input``、 ``other`` 相同。 + +返回 +:::::::: +返回计算MarginRankingLoss的可调用对象。 + +代码示例 +:::::::: + +.. code-block:: python + + + import numpy as np + import paddle + + paddle.disable_static() + + input = paddle.to_variable(np.array([[1, 2], [3, 4]]).astype("float32")) + other = paddle.to_variable(np.array([[2, 1], [2, 4]]).astype("float32")) + label = paddle.to_variable(np.array([[1, -1], [-1, -1]]).astype("float32")) + margin_rank_loss = paddle.nn.MarginRankingLoss() + loss = margin_rank_loss(input, other, label) + print(loss.numpy()) # [0.75] diff --git a/doc/paddle/api/paddle/nn/layer/loss/NLLLoss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/NLLLoss_cn.rst index 7d3e46dc66a0a6587f786de999cae3ddbcc9c5fc..f2b1559091cc5c6f211a4fa64f2eaa77e869fc3a 100644 --- a/doc/paddle/api/paddle/nn/layer/loss/NLLLoss_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/loss/NLLLoss_cn.rst @@ -1,9 +1,11 @@ +.. _cn_api_nn_loss_NLLLoss: + NLLLoss ------------------------------- -.. py:function:: paddle.nn.loss.NLLLoss(weight=None, reduction='mean', ignore_index=-100) +.. py:class:: paddle.nn.loss.NLLLoss(weight=None, ignore_index=-100, reduction='mean', name=None) -该OP计算输入input和标签label间的 `negative log likelihood loss` 损失 ，可用于训练一个 `n` 类分类器。 +该接口可创建一个NLLLoss可调用类，计算输入x和标签label间的 `negative log likelihood loss` 损失 ，可用于训练一个 `n` 类分类器。 如果提供 `weight` 参数的话，它是一个 `1-D` 的tensor, 里面的值对应类别的权重。当你的训练集样本 不均衡的话，使用这个参数是非常有用的。 @@ -28,48 +30,41 @@ NLLLoss \text{if reduction} = \text{'sum'.} \end{cases} -参数： - - **input** (Variable): - 输入 `Tensor`, 其形状为 :math:`[N, C]` , 其中 `C` 为类别数。但是对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_K]` 。数据类型为float32或float64。 - - **label** (Variable): - 输入input对应的标签值。其形状为 :math:`[N,]` 或者 :math:`[N, d_1, d_2, ..., d_K]`, 数据类型为int64。 - - **weight** (Variable, 可选): - 手动指定每个类别的权重。其默认为 `None` 。如果提供该参数的话，长度必须为 `num_classes` 。数据类型为float32或float64。 - - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算 `mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。数据类型为string。 +参数 +::::::::: + - **weight** (Tensor, 可选): - 手动指定每个类别的权重。其默认为 `None` 。如果提供该参数的话，长度必须为 `num_classes` 。数据类型为float32或float64。 - **ignore_index** (int64, 可选): - 指定一个忽略的标签值，此标签值不参与计算。默认值为-100。数据类型为int64。 + - **reduction** (str, 可选): - 指定应用于输出结果的计算方式，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算 `mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。数据类型为string。 + - **name** (str, 可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +形状 +::::::::: + - **input** (Tensor): - 输入 `Tensor`, 其形状为 :math:`[N, C]` , 其中 `C` 为类别数。但是对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_K]` 。数据类型为float32或float64。 + - **label** (Tensor): - 输入 `input` 对应的标签值。其形状为 :math:`[N,]` 或者 :math:`[N, d_1, d_2, ..., d_K]`, 数据类型为int64。 + - **output** (Tensor): - 输入 `input` 和 `label` 间的 `negative log likelihood loss` 损失。如果 `reduction` 为 `'none'` ，则输出Loss形状为 `[N, *]` 。 如果 `reduction` 为 `'sum'` 或者 `'mean'` ，则输出Loss形状为 `'[1]'` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + nll_loss = paddle.nn.layer.NLLLoss() + log_softmax = paddle.nn.LogSoftmax(axis=1) -返回：返回存储表示 `negative log likihood loss` 的损失值。 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - # declarative mode - import paddle.fluid as fluid - import numpy as np - import paddle - input_np = np.random.random(size=(10, 10)).astype(np.float32) - label_np = np.random.randint(0, 10, size=(10,)).astype(np.int64) - prog = fluid.Program() - startup_prog = fluid.Program() - place = fluid.CPUPlace() - with fluid.program_guard(prog, startup_prog): - input = fluid.data(name='input', shape=[10, 10], dtype='float32') - label = fluid.data(name='label', shape=[10], dtype='int64') - nll_loss = paddle.nn.loss.NLLLoss() - res = nll_loss(input, label) - exe = fluid.Executor(place) - static_result = exe.run( - prog, - feed={"input": input_np, - "label": label_np}, - fetch_list=[res]) - print(static_result) - - # imperative mode - import paddle.fluid.dygraph as dg - with dg.guard(place) as g: - input = dg.to_variable(input_np) - label = dg.to_variable(label_np) - output = nll_loss(input, label) - print(output.numpy()) + input_np = np.array([[0.88103855, 0.9908683 , 0.6226845 ], + [0.53331435, 0.07999352, 0.8549948 ], + [0.25879037, 0.39530203, 0.698465 ], + [0.73427284, 0.63575995, 0.18827209], + [0.05689114, 0.0862954 , 0.6325046 ]]).astype(np.float32) + label_np = np.array([0, 2, 1, 1, 0]).astype(np.int64) + place = paddle.CPUPlace() + paddle.disable_static(place) + input = paddle.to_variable(input_np) + log_out = log_softmax(input) + label = paddle.to_variable(label_np) + result = nll_loss(log_out, label) + print(result.numpy()) # [1.0720209] diff --git a/doc/paddle/api/paddle/nn/layer/loss/SmoothL1Loss_cn.rst b/doc/paddle/api/paddle/nn/layer/loss/SmoothL1Loss_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..8a5fee1e07cb45a055fc2eb65b45233d1ca6cbdd --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/loss/SmoothL1Loss_cn.rst @@ -0,0 +1,52 @@ +SmoothL1Loss +------------------------------- + +.. py:class:: paddle.nn.loss.SmoothL1Loss(reduction='mean', delta=1.0, name=None) + +该OP计算输入input和标签label间的SmoothL1损失，如果逐个元素的绝对误差低于1，则创建使用平方项的条件 +，否则为L1损失。在某些情况下，它可以防止爆炸梯度, 也称为Huber损失,该损失函数的数学计算公式如下： + + .. math:: + loss(x,y)=\\frac{1}{n}\\sum_{i}z_i + +`z_i`的计算公式如下： + + .. math:: + + \\mathop{z_i}=\\left\\{\\begin{array}{rcl} + 0.5(x_i - y_i)^2 & & {if |x_i - y_i| < delta} \\\\ + delta * |x_i - y_i| - 0.5 * delta^2 & & {otherwise} + \\end{array} \\right. + +参数 +:::::::::: + - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，数据类型为string，可选值有: `none`, `mean`, `sum` 。默认为 `mean` ，计算 `mini-batch` loss均值。设置为 `sum` 时，计算 `mini-batch` loss的总和。设置为 `none` 时，则返回loss Tensor。 + - **delta** (string, 可选): SmoothL1Loss损失的阈值参数，用于控制Huber损失对线性误差或平方误差的侧重。数据类型为float32。 默认值= 1.0。 + - **name** (string, 可选): - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +调用参数 +:::::::::: + - **input** (Tensor): 输入 `Tensor`， 数据类型为float32。其形状为 :math:`[N, C]` , 其中 `C` 为类别数。对于多维度的情形下，它的形状为 :math:`[N, C, d_1, d_2, ..., d_k]`，k >= 1。 + - **label** (Tensor): 输入input对应的标签值，数据类型为float32。数据类型和input相同。 + + + +返回：返回计算 `SmoothL1Loss` 后的损失值。 + +返回类型：Tensor + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + input = np.random.rand(3,3).astype("float32") + label = np.random.rand(3,3).astype("float32") + input = paddle.to_tensor(input_data) + label = paddle.to_tensor(label_data) + loss = paddle.nn.SmoothL1Loss() + output = loss(input, label) + print(output.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/norm/BatchNorm1d_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/BatchNorm1d_cn.rst index 3d62b0d1fb74c0e091a5e9259e5131291a26a477..c25ec52a26365319fea221ed14c0afd79eea200c 100644 --- a/doc/paddle/api/paddle/nn/layer/norm/BatchNorm1d_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/norm/BatchNorm1d_cn.rst @@ -70,5 +70,5 @@ BatchNorm1d batch_norm = paddle.nn.BatchNorm1d(1) batch_norm_out = batch_norm(x) - print(batch_norm_out.numpy) + print(batch_norm_out.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/norm/BatchNorm2d_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/BatchNorm2d_cn.rst index 38fad62b9505bb0631776fb57372a0b303f0c16c..af590ce252fa8c65fe46f01a9138bb4adac2554d 100644 --- a/doc/paddle/api/paddle/nn/layer/norm/BatchNorm2d_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/norm/BatchNorm2d_cn.rst @@ -41,7 +41,7 @@ BatchNorm2d - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果为False, 则表示每个通道的伸缩固定为1，不可改变。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 - **bias_attr** (ParamAttr, 可选) - 指定偏置参数属性的对象。如果为False, 则表示每一个通道的偏移固定为0，不可改变。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 - - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为“NCWH"或者"NCHW"。默认值：“NCHW”。 + - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为"NCHW"。默认值：“NCHW”。 - **track_running_stats** (bool, 可选) – 指示是否使用全局均值和方差。在训练时，设置为True表示在训练期间将保存全局均值和方差用于推理。推理时此属性只能设置为True。默认值：True。 - **name** (string, 可选) – BatchNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 @@ -70,5 +70,5 @@ BatchNorm2d batch_norm = paddle.nn.BatchNorm2d(1) batch_norm_out = batch_norm(x) - print(batch_norm_out.numpy) + print(batch_norm_out.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/norm/BatchNorm3d_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/BatchNorm3d_cn.rst index 9121aa9d9a445f07da9d38637c7574b749bbcadf..98152e9f539fee04642390274c00e48a33c33696 100644 --- a/doc/paddle/api/paddle/nn/layer/norm/BatchNorm3d_cn.rst +++ b/doc/paddle/api/paddle/nn/layer/norm/BatchNorm3d_cn.rst @@ -70,5 +70,5 @@ BatchNorm3d batch_norm = paddle.nn.BatchNorm3d(1) batch_norm_out = batch_norm(x) - print(batch_norm_out.numpy) + print(batch_norm_out.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/norm/GroupNorm_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/GroupNorm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..4628093cc07d714743d24e26a1ef34832f4bca67 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/norm/GroupNorm_cn.rst @@ -0,0 +1,41 @@ +.. _cn_api_nn_GroupNorm: + +GroupNorm +------------------------------- + +.. py:class:: paddle.nn.GroupNorm(num_groups, num_channels, epsilon=1e-05, weight_attr=None, bias_attr=None, data_layout='NCHW, 'name=None) + +**Group Normalization层** + +该接口用于构建 ``GroupNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。其中实现了组归一化层的功能。更多详情请参考： `Group Normalization `_ 。 + +参数： + - **num_groups** (int) - 从通道中分离出来的 ``group`` 的数目。 + - **num_channels** (int) - 输入的通道数。 + - **epsilon** (float, 可选) - 为防止方差除零，增加一个很小的值。默认值：1e-05。 + - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果为False, 表示参数不学习。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool, 可选) - 指定偏置参数属性的对象。如果为False, 表示参数不学习。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (string, 可选) - 只支持“NCHW”(num_batches，channels，height，width)格式。默认值：“NCHW”。 + - **name** (string, 可选) – GroupNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + +返回：无 + +形状： + - input: 形状为（批大小，通道数, 高度，宽度）的4-D Tensor。 + - output: 和输入形状一样。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np.random.seed(123) + x_data = np.random.random(size=(2, 6, 2, 2)).astype('float32') + x = paddle.to_tensor(x_data) + group_norm = paddle.nn.GroupNorm(num_channels=6, num_groups=6) + group_norm_out = group_norm(x) + + print(group_norm_out.numpy()) diff --git a/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm1d_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm1d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c77698a5506d9483d091474b60430e18b8d4f45b --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm1d_cn.rst @@ -0,0 +1,60 @@ +.. _cn_api_nn_InstanceNorm1d: + +InstanceNorm1d +------------------------------- + +.. py:class:: paddle.nn.InstanceNorm1d(num_features, epsilon=1e-05, momentum=0.9, weight_attr=None, bias_attr=None, track_running_stats=True, data_format="NCL", name=None): + + +该接口用于构建 ``InstanceNorm1d`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。可以处理2D或者3D的Tensor, 实现了实例归一化层（Instance Normalization Layer）的功能。更多详情请参考 : Instance Normalization: The Missing Ingredient for Fast Stylization . + +``input`` 是mini-batch的输入。 + +.. math:: + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// variance \\ + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift + + +Note: + `H` 是高度, `W` 是宽度. + + +参数： + - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果为False, 则表示每个通道的伸缩固定为1，不可改变。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **bias_attr** (ParamAttr, 可选) - 指定偏置参数属性的对象。如果为False, 则表示每一个通道的偏移固定为0，不可改变。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **track_running_stats** (bool, 可选) – 指示是否使用全局均值和方差。在训练时，设置为True表示在训练期间将保存全局均值和方差用于推理。推理时此属性只能设置为True。默认值：True。 + - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为“NC"或者"NCL"。默认值：“NCL”。 + - **name** (string, 可选) – InstanceNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + + +返回：无 + +形状： + - input: 形状为（批大小，通道数）的2-D Tensor 或（批大小, 通道数，长度）的3-D Tensor。 + - output: 和输入形状一样。 + +.. note:: +目前设置track_running_stats和momentum是无效的。之后的版本会修复此问题。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np.random.seed(123) + x_data = np.random.random(size=(2, 2, 3)).astype('float32') + x = paddle.to_tensor(x_data) + instance_norm = paddle.nn.InstanceNorm1d(2) + instance_norm_out = instance_norm(x) + + print(instance_norm_out.numpy()) + diff --git a/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm2d_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm2d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..cfb2571820a236e2991529841a984e8ae7a09ba3 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm2d_cn.rst @@ -0,0 +1,60 @@ +.. _cn_api_nn_cn_InstanceNorm2d: + +InstanceNorm2d +------------------------------- + +.. py:class:: paddle.nn.InstanceNorm2d(num_features, epsilon=1e-05, momentum=0.9, weight_attr=None, bias_attr=None, track_running_stats=True, data_format="NCHW", name=None): + + +该接口用于构建 ``InstanceNorm2d`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。可以处理2D或者3D的Tensor, 实现了实例归一化层（Instance Normalization Layer）的功能。更多详情请参考 : Instance Normalization: The Missing Ingredient for Fast Stylization . + +``input`` 是mini-batch的输入。 + +.. math:: + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// variance \\ + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift + +Note: + `H` 是高度, `W` 是宽度. + + +参数： + - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果为False, 则表示每个通道的伸缩固定为1，不可改变。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **bias_attr** (ParamAttr, 可选) - 指定偏置参数属性的对象。如果为False, 则表示每一个通道的偏移固定为0，不可改变。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **track_running_stats** (bool, 可选) – 指示是否使用全局均值和方差。在训练时，设置为True表示在训练期间将保存全局均值和方差用于推理。推理时此属性只能设置为True。默认值：True。 + - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为“NCHW"。默认值：“NCHW”。 + - **name** (string, 可选) – InstanceNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + + +返回：无 + +形状： + - input: 形状为（批大小，通道数，高度，宽度）的4-D Tensor。 + - output: 和输入形状一样。 + +.. note:: +目前设置track_running_stats和momentum是无效的。之后的版本会修复此问题。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np.random.seed(123) + x_data = np.random.random(size=(2, 2, 2, 3)).astype('float32') + x = paddle.to_tensor(x_data) + instance_norm = paddle.nn.InstanceNorm2d(2) + instance_norm_out = instance_norm(x) + + print(instance_norm_out.numpy()) + + diff --git a/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm3d_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm3d_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e1c4ab4a9e547f99e7f8451fa6c2747887c9c10d --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/norm/InstanceNorm3d_cn.rst @@ -0,0 +1,58 @@ +.. _cn_api_nn_cn_InstanceNorm3d: + +InstanceNorm3d +------------------------------- + +.. py:class:: paddle.nn.InstanceNorm3d(num_features, epsilon=1e-05, momentum=0.9, weight_attr=None, bias_attr=None, track_running_stats=True, data_format="NCDHW", name=None): + +该接口用于构建 ``InstanceNorm3d`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。可以处理5D的Tensor, 实现了实例归一化层（Instance Normalization Layer）的功能。更多详情请参考 : Instance Normalization: The Missing Ingredient for Fast Stylization . + +``input`` 是mini-batch的输入。 + +.. math:: + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// variance \\ + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift + +Note: + `H` 是高度, `W` 是宽度. + + +参数： + - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果为False, 则表示每个通道的伸缩固定为1，不可改变。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **bias_attr** (ParamAttr, 可选) - 指定偏置参数属性的对象。如果为False, 则表示每一个通道的偏移固定为0，不可改变。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **track_running_stats** (bool, 可选) – 指示是否使用全局均值和方差。在训练时，设置为True表示在训练期间将保存全局均值和方差用于推理。推理时此属性只能设置为True。默认值：True。 + - **data_format** (string, 可选) - 指定输入数据格式，数据格式可以为"NCDHW"。默认值：“NCDHW”。 + - **name** (string, 可选) – InstanceNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + + +返回：无 + +形状： + - input: 形状为5-D Tensor。 + - output: 和输入形状一样。 + +.. note:: +目前设置track_running_stats和momentum是无效的。之后的版本会修复此问题。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np.random.seed(123) + x_data = np.random.random(size=(2, 2, 2, 2, 3)).astype('float32') + x = paddle.to_tensor(x_data) + instance_norm = paddle.nn.InstanceNorm3d(2) + instance_norm_out = instance_norm(x) + + print(instance_norm_out.numpy()) + diff --git a/doc/paddle/api/paddle/nn/layer/norm/LayerNorm_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/LayerNorm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..6329fc658a85c632010a57ccbb5cfe671fbdb379 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/norm/LayerNorm_cn.rst @@ -0,0 +1,54 @@ +.. _cn_api_nn_LayerNorm: + +LayerNorm +------------------------------- + +.. py:class:: paddle.nn.LayerNorm(normalized_shape, epsilon=1e-05, weight_attr=None, bias_attr=None, name=None) + +该接口用于构建 ``LayerNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。其中实现了层归一化层（Layer Normalization Layer）的功能，其可以应用于小批量输入数据。更多详情请参考：`Layer Normalization `_ + +计算公式如下 + +.. math:: + \\\mu=\frac{1}{H}\sum_{i=1}^{H}x_i\\ + + \\\sigma=\sqrt{\frac{1}{H}\sum_i^H{(x_i-\mu)^2} + \epsilon}\\ + + \\y=f(\frac{g}{\sigma}(x-\mu) + b)\\ + +- :math:`x` : 该层神经元的向量表示 +- :math:`H` : 层中隐藏神经元个数 +- :math:`\epsilon` : 添加较小的值到方差中以防止除零 +- :math:`g` : 可训练的比例参数 +- :math:`b` : 可训练的偏差参数 + + +参数： + - **normalized_shape** (int 或 list 或 tuple) – 需规范化的shape，期望的输入shape为 ``[*, normalized_shape[0], normalized_shape[1], ..., normalized_shape[-1]]`` 。如果是单个整数，则此模块将在最后一个维度上规范化（此时最后一维的维度需与该参数相同）。 + - **epsilon** (float, 可选) - 指明在计算过程中是否添加较小的值到方差中以防止除零。默认值：1e-05。 + - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果为False固定为1，不进行学习。默认值为None, 表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr, 可选) - 指定偏置参数属性的对象。如果为False固定为0，不进行学习。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **name** (string, 可选) – LayerNorm的名称, 默认值为None。更多信息请参见 :ref:`api_guide_Name` 。 + +返回：无 + +形状： + - input: 2-D, 3-D, 4-D或5D 的Tensor。 + - output: 和输入形状一样。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np.random.seed(123) + x_data = np.random.random(size=(2, 2, 2, 3)).astype('float32') + x = paddle.to_tensor(x_data) + layer_norm = paddle.nn.LayerNorm(x_data.shape[1:]) + layer_norm_out = layer_norm(x) + + print(layer_norm_out.numpy()) + diff --git a/doc/paddle/api/paddle/nn/layer/norm/SyncBatchNorm_cn.rst b/doc/paddle/api/paddle/nn/layer/norm/SyncBatchNorm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c4d2b742d452e9f702a20a1af6d73f24332fc5bb --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/norm/SyncBatchNorm_cn.rst @@ -0,0 +1,64 @@ +.. _cn_api_nn_SyncBatchNorm: + +SyncBatchNorm +------------------------------- + +.. py:class:: paddle.nn.SyncBatchNorm(num_features, epsilon=1e-5, momentum=0.9, track_running_stats=True, weight_attr=None, bias_attr=None, data_format='NCHW', name=None) + +该接口用于构建 ``SyncBatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。实现了跨卡GPU同步的批归一化(Cross-GPU Synchronized Batch Normalization Layer)的功能，可用在其他层（类似卷积层和全连接层）之后进行归一化操作。根据所有GPU同一批次的数据按照通道计算的均值和方差进行归一化。更多详情请参考 : `Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ + +当模型处于训练模式时，:math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 是所有GPU上同一minibatch的统计数据。计算公式如下： + +.. math:: + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mini-batch-mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// mini-batch-variance \\ + +- :math:`x` : 所有GPU上同一批输入数据 +- :math:`m` : 所有GPU上同一批次数据的大小 + +当模型处于评估模式时，:math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 是全局（或运行）统计数据（moving_mean和moving_variance， 这两个统计量通常来自预先训练好的模型）。计算公式如下： + +.. math:: + + moving\_mean = moving\_mean * momentum + \mu_{\beta} * (1. - momentum) \quad &// global mean \\ + moving\_variance = moving\_variance * momentum + \sigma_{\beta}^{2} * (1. - momentum) \quad &// global variance \\ + +归一化函数公式如下： + +.. math:: + + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift \\ + +- :math:`\epsilon` : 添加较小的值到方差中以防止除零 +- :math:`\gamma` : 可训练的比例参数 +- :math:`\beta` : 可训练的偏差参数 + +参数： + - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 + - **epsilon** (float, 可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **momentum** (float, 可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **weight_attr** (ParamAttr|bool, 可选) - 指定权重参数属性的对象。如果设置为 ``False`` ，则表示本层没有可训练的权重参数。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool, 可选) - 指定偏置参数属性的对象。如果设置为 ``False`` ，则表示本层没有可训练的偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **track_running_stats** （bool, 可选）- 是否计算全局均值和方差。默认: ``True`` ，表示计算全局均值和方差。 + +形状： + - input: 一个二维到五维的 ``Tensor`` 。 + - output: 和input 相同形状的 ``Tensor`` 。 + +**代码示例** + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + x = np.array([[[[0.3, 0.4], [0.3, 0.07]], [[0.83, 0.37], [0.18, 0.93]]]]).astype('float32') + paddle.disable_static() + x = paddle.to_tensor(x) + if paddle.fluid.is_compiled_with_cuda(): + sync_batch_norm = nn.SyncBatchNorm(2) + hidden1 = sync_batch_norm(x) + print(hidden1.numpy()) + # [[[[0.26824948, 1.0936325],[0.26824948, -1.6301316]],[[ 0.8095662, -0.665287],[-1.2744656, 1.1301866 ]]]] + diff --git a/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool1d_cn.rst b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..b7ea3869b9b9cfad8c3c9a77a72aa19b1f80e0a8 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool1d_cn.rst @@ -0,0 +1,66 @@ +.. _cn_api_nn_AdaptiveAvgPool1d: + + +AdaptiveAvgPool1d +------------------------------- + +.. py:function:: paddle.nn.AdaptiveAvgPool1d(output_size, name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算1D的自适应平均池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度. + +计算公式如下: + +.. math:: + + lstart &= floor(i * L_{in} / L_{out}) + + lend &= ceil((i + 1) * L_{in} / L_{out}) + + Output(i) &= \frac{sum(Input[lstart:lend])}{(lstart - lend)} + + +参数 +::::::::: + - **output_size** (int): 算子输出特征图的长度，其数据类型为int。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCL格式的3-D Tensor。 其数据类型为float32或者float64。 + - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCL格式的3-D Tensor。 其数据类型与输入x相同。 + +返回 +::::::::: +计算AdaptiveAvgPool1d的可调用对象 + +抛出异常 +::::::::: + - ``ValueError`` - ``output_size`` 应是一个整数。 + +代码示例 +::::::::: + +.. code-block:: python + + # average adaptive pool1d + # suppose input data in shape of [N, C, L], `output_size` is m or [m], + # output shape is [N, C, m], adaptive pool divide L dimension + # of input data into m grids averagely and performs poolings in each + # grid to get output. + # adaptive avg pool performs calculations as follow: + # + # for i in range(m): + # lstart = floor(i * L / m) + # lend = ceil((i + 1) * L / m) + # output[:, :, i] = sum(input[:, :, lstart: lend])/(lstart - lend) + # + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + AdaptiveAvgPool1d = nn.layer.AdaptiveAvgPool1d(output_size=16) + pool_out = AdaptiveAvgPool1d(data) + # pool_out shape: [1, 3, 16] diff --git a/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool2d_cn.rst b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool2d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..6d6eaa5044f9b2781c46f449240e8bf158c3fb50 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool2d_cn.rst @@ -0,0 +1,72 @@ +AdaptiveAvgPool2d +------------------------------- + +.. py:function:: paddle.nn.AdaptiveAvgPool2d(output_size, data_format="NCHW", name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算2D的自适应平均池化。输入和输出都是4-D Tensor， +默认是以 `NCHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `H` 是输入特征的高度, `H` 是输入特征的宽度。 + +计算公式如下: + +.. math:: + + hstart &= floor(i * H_{in} / H_{out}) + + hend &= ceil((i + 1) * H_{in} / H_{out}) + + wstart &= floor(j * W_{in} / W_{out}) + + wend &= ceil((j + 1) * W_{in} / W_{out}) + + Output(i ,j) &= \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)} + + +参数 +::::::::: + - **output_size** (int|list|turple): 算子输出特征图的尺寸，如果其是list或turple类型的数值，必须包含两个元素，H和W。H和W既可以是int类型值也可以是None，None表示与输入特征尺寸相同。 + - **data_format** (str): 输入和输出的数据格式，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，高度，宽度），即NCHW格式的4-D Tensor。 其数据类型为float16, float32, float64, int32或int64。 + - **output** (Tensor): 默认形状为（批大小，通道数，输出特征高度，输出特征宽度），即NCHW格式的4-D Tensor。 其数据类型与输入相同。 + + +返回 +::::::::: +计算AdaptiveAvgPool2d的可调用对象 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 + +代码示例 +::::::::: + +.. code-block:: python + + # adaptive avg pool2d + # suppose input data in shape of [N, C, H, W], `output_size` is [m, n], + # output shape is [N, C, m, n], adaptive pool divide H and W dimensions + # of input data into m * n grids averagely and performs poolings in each + # grid to get output. + # adaptive avg pool performs calculations as follow: + # + # for i in range(m): + # for j in range(n): + # hstart = floor(i * H / m) + # hend = ceil((i + 1) * H / m) + # wstart = floor(i * W / n) + # wend = ceil((i + 1) * W / n) + # output[:, :, i, j] = avg(input[:, :, hstart: hend, wstart: wend]) + # + import paddle + import numpy as np + paddle.disable_static() + input_data = np.random.rand(2, 3, 32, 32) + x = paddle.to_tensor(input_data) + # x.shape is [2, 3, 32, 32] + adaptive_avg_pool = paddle.nn.AdaptiveAvgPool2d(output_size=3) + pool_out = adaptive_avg_pool(x = x) + # pool_out.shape is [2, 3, 3, 3] \ No newline at end of file diff --git a/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool3d_cn.rst b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool3d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..4315f960cdf53e6f6f25c1b06d600d84d3b03dd2 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveAvgPool3d_cn.rst @@ -0,0 +1,78 @@ +AdaptiveAvgPool3d +------------------------------- + +.. py:function:: paddle.nn.AdaptiveAvgPool3d(output_size, data_format="NCDHW", name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算3D的自适应平均池化。输入和输出都是5-D Tensor， +默认是以 `NCDHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `D` 是特征图长度, `H` 是输入特征的高度, `H` 是输入特征的宽度。 + +计算公式如下: + +.. math:: + + dstart &= floor(i * D_{in} / D_{out}) + + dend &= ceil((i + 1) * D_{in} / D_{out}) + + hstart &= floor(j * H_{in} / H_{out}) + + hend &= ceil((j + 1) * H_{in} / H_{out}) + + wstart &= floor(k * W_{in} / W_{out}) + + wend &= ceil((k + 1) * W_{in} / W_{out}) + + Output(i ,j, k) &= \frac{sum(Input[dstart:dend, hstart:hend, wstart:wend])}{(dend - dstart) * (hend - hstart) * (wend - wstart)} + +参数 +::::::::: + - **output_size** (int|list|turple): 算子输出特征图的尺寸，如果其是list或turple类型的数值，必须包含三个元素，D，H和W。D，H和W既可以是int类型值也可以是None，None表示与输入特征尺寸相同。 + - **data_format** (str): 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，D是特征长度，H是特征高度，W是特征宽度。默认值："NCDHW"。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，长度，高度，宽度），即NCDHW格式的5-D Tensor。 其数据类型为float16, float32, float64, int32或int64. + - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度，输出特征高度，输出特征宽度），即NCDHW格式的5-D Tensor。 其数据类型与输入相同。 + + +返回 +::::::::: +计算AdaptiveAvgPool3d的可调用对象 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``data_format`` 既不是"NCDHW"也不是"NDHWC"。 + +代码示例 +::::::::: + +.. code-block:: python + + # adaptive avg pool3d + # suppose input data in shape of [N, C, D, H, W], `output_size` is [l, m, n], + # output shape is [N, C, l, m, n], adaptive pool divide D, H and W dimensions + # of input data into l * m * n grids averagely and performs poolings in each + # grid to get output. + # adaptive avg pool performs calculations as follow: + # + # for i in range(l): + # for j in range(m): + # for k in range(n): + # dstart = floor(i * D / l) + # dend = ceil((i + 1) * D / l) + # hstart = floor(j * H / m) + # hend = ceil((j + 1) * H / m) + # wstart = floor(k * W / n) + # wend = ceil((k + 1) * W / n) + # output[:, :, i, j, k] = + # avg(input[:, :, dstart:dend, hstart: hend, wstart: wend]) + import paddle + import numpy as np + paddle.disable_static() + input_data = np.random.rand(2, 3, 8, 32, 32) + x = paddle.to_tensor(input_data) + # x.shape is [2, 3, 8, 32, 32] + adaptive_avg_pool = paddle.nn.AdaptiveAvgPool3d(output_size=3) + pool_out = adaptive_avg_pool(x = x) + # pool_out = [2, 3, 3, 3, 3] diff --git a/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveMaxPool1d_cn.rst b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveMaxPool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..3d11df5b51d3f6bbede8b92e36091614fd868bc3 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/pooling/AdaptiveMaxPool1d_cn.rst @@ -0,0 +1,72 @@ +.. _cn_api_nn_AdaptiveMaxPool1d: + + +AdaptiveMaxPool1d +------------------------------- + +.. py:function:: paddle.nn.AdaptiveMaxPool1d(output_size, return_indices=False, name=None) + +该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算1D的自适应平均池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度. + +计算公式如下: + +.. math:: + + lstart &= floor(i * L_{in} / L_{out}) + + lend &= ceil((i + 1) * L_{in} / L_{out}) + + Output(i) &= max(Input[lstart:lend]) + + +参数 +::::::::: + - **output_size** (int|list|tuple): 算子输出特征图的长度，其数据类型为int,list或tuple。 + - **return_indices** (bool): 如果设置为True，则会与输出一起返回最大值的索引，默认为False。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +形状 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCL格式的3-D Tensor。 其数据类型为float32或者float64。 + - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCL格式的3-D Tensor。 其数据类型与输入x相同。 + +返回 +::::::::: +计算AdaptiveMaxPool1d的可调用对象 + +抛出异常 +::::::::: + - ``ValueError`` - ``output_size`` 应是一个整数或长度为1的list，tuple + +代码示例 +::::::::: + +.. code-block:: python + + # max adaptive pool1d + # suppose input data in shape of [N, C, L], `output_size` is m or [m], + # output shape is [N, C, m], adaptive pool divide L dimension + # of input data into m grids averagely and performs poolings in each + # grid to get output. + # adaptive max pool performs calculations as follow: + # + # for i in range(m): + # lstart = floor(i * L / m) + # lend = ceil((i + 1) * L / m) + # output[:, :, i] = max(input[:, :, lstart: lend]) + # + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + AdaptiveMaxPool1d = nn.layer.AdaptiveMaxPool1d(output_size=16) + pool_out = AdaptiveMaxPool1d(data) + # pool_out shape: [1, 3, 16] + + # for return_indices = true + AdaptiveMaxPool1d = nn.layer.AdaptiveMaxPool1d(output_size=16, return_indices=True) + pool_out, indices = AdaptiveMaxPool1d(data) + # pool_out shape: [1, 3, 16], indices shape: [1, 3, 16] diff --git a/doc/paddle/api/paddle/nn/layer/pooling/AvgPool1d_cn.rst b/doc/paddle/api/paddle/nn/layer/pooling/AvgPool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..c24c89ec51ce367586385684a750ef4700aa6b08 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/pooling/AvgPool1d_cn.rst @@ -0,0 +1,59 @@ +.. _cn_api_nn_AvgPool1d: + + +AvgPool1d +------------------------------- + +.. py:function:: paddle.nn.AvgPool1d(kernel_size, stride=None, padding=0, count_include_pad=True, ceil_mode=False, name=None) + +该算子根据输入 `x` , `kernel_size` 等参数对一个输入Tensor计算1D的平均池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度。 + +假设输入形状是(N, C, L)，输出形状是 (N, C, L_{out})，卷积核尺寸是k, 1d平均池化计算公式如下: + +.. math:: + + Output(N_i, C_i, l) = mean(Input[N_i, C_i, stride \times l:stride \times l+k]) + +参数 +::::::::: + - **kernel_size** (int|list|tuple): 池化核的尺寸大小. 如果kernel_size为list或tuple类型, 其必须包含一个整数, 最终池化核的大小为该数值。 + - **stride** (int|list|tuple): 池化操作步长. 如果stride为list或tuple类型, 其必须包含一个整数，最终池化操作的步长为该数值。 + - **padding** (string|int|list|tuple): 池化补零的方式. 如果padding是一个字符串，则必须为 `SAME` 或者 `VALID` 。如果是turple或者list类型， 则应是 `[pad_left, pad_right]` 形式。如果padding是一个非0值，那么表示会在输入的两端都padding上同样长度的0。 + - **count_include_pad** (bool): 是否用额外padding的值计算平均池化结果，默认为True。 + - **ceil_mode** (bool): 是否用ceil函数计算输出的height和width，如果设置为False, 则使用floor函数来计算，默认为False。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +形状 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，长度），即NCL格式的3-D Tensor。 其数据类型为float32或float64. + - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCL格式的3-D Tensor。 其数据类型与输入x相同。 + +返回 +::::::::: +计算AvgPool1d的可调用对象 + + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``padding`` 是字符串但不是 "SAME" 和 "VALID" 。 + - ``ValueError`` - 如果 ``padding`` 是 "VALID" 但 `ceil_mode` 被设置为True。 + - ``ValueError`` - 如果 ``padding`` 是一个长度大于1的list或turple。 + - ``ShapeError`` - 如果输入x不是一个3-D Tensor。 + - ``ShapeError`` - 如果计算得到的输出形状小于等于0。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + AvgPool1d = nn.layer.AvgPool1d(kernel_size=2, stride=2, padding=0) + pool_out = AvgPool1d(data) + # pool_out shape: [1, 3, 16] diff --git a/doc/paddle/api/paddle/nn/layer/pooling/MaxPool1d_cn.rst b/doc/paddle/api/paddle/nn/layer/pooling/MaxPool1d_cn.rst new file mode 100755 index 0000000000000000000000000000000000000000..cd6c92f9a064e442786f394ad3f61ccaed648611 --- /dev/null +++ b/doc/paddle/api/paddle/nn/layer/pooling/MaxPool1d_cn.rst @@ -0,0 +1,62 @@ +.. _cn_api_nn_MaxPool1d: + + +MaxPool1d +------------------------------- + +.. py:function:: paddle.nn.MaxPool1d(kernel_size, stride=None, padding=0, return_indices=False, ceil_mode=False, name=None) + +该算子根据输入 `x` , `kernel_size` 等参数对一个输入Tensor计算1D的最大值池化。输入和输出都是3-D Tensor， +默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `L` 是输入特征的长度。 + +假设输入形状是(N, C, L)，输出形状是 (N, C, L_{out})，卷积核尺寸是k, 1d最大值池化计算公式如下: + +.. math:: + + Output(N_i, C_i, l) = max(Input[N_i, C_i, stride \times l:stride \times l+k]) + +参数 +::::::::: + - **kernel_size** (int|list|tuple): 池化核的尺寸大小. 如果kernel_size为list或tuple类型, 其必须包含一个整数, 最终池化核的大小为该数值。 + - **stride** (int|list|tuple): 池化操作步长. 如果stride为list或tuple类型, 其必须包含一个整数，最终池化操作的步长为该数值。 + - **padding** (string|int|list|tuple): 池化补零的方式. 如果padding是一个字符串，则必须为 `SAME` 或者 `VALID` 。 如果是turple或者list类型， 则应是 `[pad_left, pad_right]` 形式。如果padding是一个非0值，那么表示会在输入的两端都padding上同样长度的0。 + - **return_indices** (bool): 是否返回最大值的索引，默认为False。 + - **ceil_mode** (bool): 是否用ceil函数计算输出的height和width，如果设置为False, 则使用floor函数来计算，默认为False。 + - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +形状 +::::::::: + - **x** (Tensor): 默认形状为（批大小，通道数，长度），即NCL格式的3-D Tensor。 其数据类型为float32或float64. + - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCL格式的3-D Tensor。 其数据类型与输入x相同。 + +返回 +::::::::: +计算MaxPool1d的可调用对象 + +抛出异常 +::::::::: + - ``ValueError`` - 如果 ``padding`` 是字符串但不是 "SAME" 和 "VALID" 。 + - ``ValueError`` - 如果 ``padding`` 是 "VALID" 但 `ceil_mode` 被设置为True。 + - ``ValueError`` - 如果 ``padding`` 是一个长度大于1的list或turple。 + - ``ShapeError`` - 如果输入x不是一个3-D Tensor。 + - ``ShapeError`` - 如果计算得到的输出形状小于等于0。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import paddle.nn as nn + import numpy as np + paddle.disable_static() + + data = paddle.to_variable(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32)) + MaxPool1d = nn.layer.MaxPool1d(kernel_size=2, stride=2, padding=0) + pool_out = MaxPool1d(data) + # pool_out shape: [1, 3, 16] + + MaxPool1d = nn.layer.MaxPool1d(kernel_size=2, stride=2, padding=0, return_indices=True) + pool_out, indices = MaxPool1d(data) + # pool_out shape: [1, 3, 16], indices shape: [1, 3, 16] diff --git a/doc/paddle/api/paddle/nn/utils/weight_norm_hook/remove_weight_norm_cn.rst b/doc/paddle/api/paddle/nn/utils/weight_norm_hook/remove_weight_norm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..3c14b5b625d9cdff1024ae9fcafb0a5057cdd6a0 --- /dev/null +++ b/doc/paddle/api/paddle/nn/utils/weight_norm_hook/remove_weight_norm_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_nn_cn_remove_weight_norm: + +remove_weight_norm +------------------------------- + +.. py:function:: paddle.nn.utils.remove_weight_norm(layer, name='weight') + +移除传入 ``layer`` 中的权重归一化。 + +参数： + - **layer** (paddle.nn.Layer) - 要添加权重归一化的层。 + - **name** (str, 可选) - 权重参数的名字。默认：'weight'. + +返回： + ``Layer`` , 移除权重归一化hook之后的层 + +**代码示例** + +.. code-block:: python + + import paddle + from paddle.nn import Conv2d + from paddle.nn.utils import weight_norm, remove_weight_norm + paddle.disable_static() + conv = Conv2d(3, 5, 3) + wn = weight_norm(conv) + remove_weight_norm(conv) + # print(conv.weight_g) + # AttributeError: 'Conv2D' object has no attribute 'weight_g' diff --git a/doc/paddle/api/paddle/nn/utils/weight_norm_hook/weight_norm_cn.rst b/doc/paddle/api/paddle/nn/utils/weight_norm_hook/weight_norm_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c427c956be98b56fcffb88fbf5b1fcb12da9dc65 --- /dev/null +++ b/doc/paddle/api/paddle/nn/utils/weight_norm_hook/weight_norm_cn.rst @@ -0,0 +1,38 @@ +.. _cn_api_nn_cn_weight_norm: + +weight_norm +------------------------------- + +.. py:function:: paddle.nn.utils.weight_norm(layer, name='weight', dim=0) + +该接口根据以下公式对传入的 ``layer`` 中的权重参数进行归一化: + +.. math:: + \mathbf{w} = g \dfrac{v}{\|v\|} + +权重归一化可以将神经网络中权重向量的长度与其方向解耦，权重归一化可以用两个变量(例如: 代表长度的变量 `weight_g` 和代表方向的变量 `weight_v`)来代替由名字(例如: `weight`)指定的变量。详细可以参考论文: `A Simple Reparameterization to Accelerate Training of Deep Neural Networks `_ + +参数： + - **layer** (paddle.nn.Layer) - 要添加权重归一化的层。 + - **name** (str, 可选) - 权重参数的名字。默认：'weight'. + - **dim** (int|None, 可选) - 进行归一化操作的切片所在维度，是小于权重Tensor rank的非负数。比如卷积的权重shape是 [cout,cin,kh,kw] , rank是4，则dim可以选0,1,2,3；fc的权重shape是 [cout,cin] ，rank是2，dim可以选0，1。 如果为None就对所有维度上的元素做归一化。默认：0。 + +返回： + ``Layer`` , 添加了权重归一化hook的层 + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + from paddle.nn import Conv2d + from paddle.nn.utils import weight_norm + x = np.array([[[[0.3, 0.4], [0.3, 0.07]], [[0.83, 0.37], [0.18, 0.93]]]]).astype('float32') + paddle.disable_static() + conv = Conv2d(3, 5, 3) + wn = weight_norm(conv) + print(conv.weight_g.shape) + # [5] + print(conv.weight_v.shape) + # [5, 3, 3, 3] diff --git a/doc/paddle/api/paddle/optimizer/AdamW_cn.rst b/doc/paddle/api/paddle/optimizer/AdamW_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..352cfcf892d1b450585a74651b78e5017d98aef3 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/AdamW_cn.rst @@ -0,0 +1,241 @@ +.. _cn_api_paddle_optimizer_AdamW: + +AdamW +------------------------------- + +.. py:class:: paddle.optimizer.AdamW(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=0.01, apply_decay_param_fun=None, grad_clip=None, name=None, lazy_mode=False) + + + + +AdamW优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION 论文 `,用来解决Adam优化器中L2正则化失效的问题。 + +其参数更新的计算公式如下： + +.. math:: + \\t = t + 1 +.. math:: + moment\_1\_out=\beta_1∗moment\_1+(1−\beta_1)∗grad +.. math:: + moment\_2\_out=\beta_2∗moment\_2+(1−\beta_2)∗grad*grad +.. math:: + learning\_rate=learning\_rate*\frac{\sqrt{1-\beta_2^t}}{1-\beta_1^t} +.. math:: + param\_out=param-learning\_rate*(\frac{moment\_1}{\sqrt{moment\_2}+\epsilon} + \lambda * param) + +相关论文：`Adam: A Method for Stochastic Optimization `_ + +参数: + - **learning_rate** (float|_LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler类，默认值为0.001 + - **beta1** (float|Tensor, 可选) - 一阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Tensor类型。默认值为0.9 + - **beta2** (float|Tensor, 可选) - 二阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Tensor类型。默认值为0.999 + - **epsilon** (float, 可选) - 保持数值稳定性的短浮点类型值，默认值为1e-08 + - **parameters** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 + - **weight_decay** (float|Tensor, 可选) - 权重衰减系数，是一个float类型或者shape为[1] ，数据类型为float32的Tensor类型。默认值为0.01 + - **apply_decay_param_fun** (function|None, 可选): 传入函数时，只有可以使 apply_decay_param_fun(Tensor)==True的Tensor会更新参数。只有在想要指定要更新的参数时使用。默认值为None + - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 + 默认值为None，此时将不进行梯度裁剪。 + - **name** (str, 可选)- 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None + - **lazy_mode** （bool, 可选） - 设为True时，仅更新当前具有梯度的元素。官方Adam算法有两个移动平均累加器（moving-average accumulators）。累加器在每一步都会更新。在密集模式和稀疏模式下，两条移动平均线的每个元素都会更新。如果参数非常大，那么更新可能很慢。 lazy mode仅更新当前具有梯度的元素，所以它会更快。但是这种模式与原始的算法有不同的描述，可能会导致不同的结果，默认为False + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + adam = paddle.optimizer.AdamW(weight_decay=0.01, learning_rate=0.1, + parameters=linear.parameters()) + out.backward() + adam.step() + adam.clear_grad() + + +.. py:method:: step() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +执行一次优化器并进行参数更新。 + +返回：None。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + adam = paddle.optimizer.AdamW(learning_rate = 0.01, + weight_decay = 0.01, + parameters = linear.parameters()) + out = linear(a) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: minimize(loss, startup_program=None, parameters=None, no_grad_set=None) + +为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameters中的Parameters，最小化网络损失值loss。 + +参数： + - **loss** (Tensor) – 需要最小化的损失值变量 + - **startup_program** (Program, 可选) – 用于初始化parameters中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` + - **parameters** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter + - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None + +返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。在静态图模式下，该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.Adam(learning_rate=0.1, + parameters=linear.parameters(), + weight_decay=0.01) + out.backward() + adam.minimize(loss) + adam.clear_grad() + +.. py:method:: clear_grad() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + + +清除需要优化的参数的梯度。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + optimizer = paddle.optimizer.AdamW(weight_decay=0.01, + learning_rate=0.02, + parameters=linear.parameters()) + out = linear(a) + out.backward() + optimizer.step() + optimizer.clear_grad() + +.. py:method:: set_lr(value) + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +手动设置当前 ``optimizer`` 的学习率。当使用_LRScheduler时，无法使用该API手动设置学习率，因为这将导致冲突。 + +参数： + value (float) - 需要设置的学习率的值。 + +返回：None + +**代码示例** + +.. code-block:: python + + import paddle + paddle.disable_static() + linear = paddle.nn.Linear(10, 10) + + adam = paddle.optimizer.AdamW(weight_decay=0.01, + learning_rate=0.1, parameters=linear.parameters()) + + # set learning rate manually by python float value + lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] + for i in range(5): + adam.set_lr(lr_list[i]) + lr = adam.get_lr() + print("current lr is {}".format(lr)) + # Print: + # current lr is 0.2 + # current lr is 0.3 + # current lr is 0.4 + # current lr is 0.5 + # current lr is 0.6 + +.. py:method:: get_lr() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +获取当前步骤的学习率。当不使用_LRScheduler时，每次调用的返回值都相同，否则返回当前步骤的学习率。 + +返回：float，当前步骤的学习率。 + + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + # example1: _LRScheduler is not used, return value is all the same + paddle.disable_static() + emb = paddle.nn.Embedding(10, 10, sparse=False) + adam = paddle.optimizer.AdamW(learning_rate=0.001, parameters = emb.parameters(),weight_decay=0.01) + lr = adam.get_lr() + print(lr) # 0.001 + + # example2: PiecewiseLR is used, return the step learning rate + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.reduce_mean(out) + + bd = [2, 4, 6, 8] + value = [0.2, 0.4, 0.6, 0.8, 1.0] + scheduler = paddle.optimizer.PiecewiseLR(bd, value, 0) + adam = paddle.optimizer.AdamW(scheduler, + parameters=linear.parameters(), + weight_decay=0.01) + + # first step: learning rate is 0.2 + np.allclose(adam.get_lr(), 0.2, rtol=1e-06, atol=0.0) # True + + # learning rate for different steps + ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] + for i in range(12): + adam.step() + lr = adam.get_lr() + scheduler.step() + np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True diff --git a/doc/paddle/api/paddle/optimizer/Adam_cn.rst b/doc/paddle/api/paddle/optimizer/Adam_cn.rst index 2c8f8e567ab30678e7e346733c4f9b2928df4623..6c57911eddad02aa0b43c62bb6230fd6a188112e 100644 --- a/doc/paddle/api/paddle/optimizer/Adam_cn.rst +++ b/doc/paddle/api/paddle/optimizer/Adam_cn.rst @@ -1,16 +1,262 @@ -.. _cn_api_fluid_optimizer_Adam: +.. _cn_api_paddle_optimizer_Adam: Adam ------------------------------- -.. py:attribute:: paddle.fluid.optimizer.Adam +.. py:class:: paddle.optimizer.Adam(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, name=None, lazy_mode=False) -``AdamOptimizer`` 的别名 +Adam优化器出自 `Adam论文 `_ 的第二节，能够利用梯度的一阶矩估计和二阶矩估计动态调整每个参数的学习率。 +其参数更新的计算公式如下： +.. math:: + \\t = t + 1 +.. math:: + moment\_1\_out=\beta_1∗moment\_1+(1−\beta_1)∗grad +.. math:: + moment\_2\_out=\beta_2∗moment\_2+(1−\beta_2)∗grad*grad +.. math:: + learning\_rate=learning\_rate*\frac{\sqrt{1-\beta_2^t}}{1-\beta_1^t} +.. math:: + param\_out=param-learning\_rate*\frac{moment\_1}{\sqrt{moment\_2}+\epsilon}\\ +相关论文：`Adam: A Method for Stochastic Optimization `_ +参数: + - **learning_rate** (float|_LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler类，默认值为0.001 + - **beta1** (float|Tensor, 可选) - 一阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Tensor类型。默认值为0.9 + - **beta2** (float|Tensor, 可选) - 二阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Tensor类型。默认值为0.999 + - **epsilon** (float, 可选) - 保持数值稳定性的短浮点类型值，默认值为1e-08 + - **parameters** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 + - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是float类型的L2正则化系数或者正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 + :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； + 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 + - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 + 默认值为None，此时将不进行梯度裁剪。 + - **name** (str, 可选)- 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None + - **lazy_mode** （bool, 可选） - 设为True时，仅更新当前具有梯度的元素。官方Adam算法有两个移动平均累加器（moving-average accumulators）。累加器在每一步都会更新。在密集模式和稀疏模式下，两条移动平均线的每个元素都会更新。如果参数非常大，那么更新可能很慢。 lazy mode仅更新当前具有梯度的元素，所以它会更快。但是这种模式与原始的算法有不同的描述，可能会导致不同的结果，默认为False + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + adam = paddle.optimizer.Adam(learning_rate=0.1, + parameters=linear.parameters()) + out.backward() + adam.step() + adam.clear_grad() + +.. code-block:: python + + # Adam with beta1/beta2 as Tensor and weight_decay as float + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.Adam(learning_rate=0.1, + parameters=linear.parameters(), + beta1=beta1, + beta2=beta2, + weight_decay=0.01) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: step() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +执行一次优化器并进行参数更新。 + +返回：None。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + adam = paddle.optimizer.Adam(learning_rate = 0.01, + parameters = linear.parameters()) + out = linear(a) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: minimize(loss, startup_program=None, parameters=None, no_grad_set=None) + +为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameters中的Parameters，最小化网络损失值loss。 + +参数： + - **loss** (Tensor) – 需要最小化的损失值变量 + - **startup_program** (Program, 可选) – 用于初始化parameters中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` + - **parameters** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter + - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None + +返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。在静态图模式下，该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.Adam(learning_rate=0.1, + parameters=linear.parameters(), + weight_decay=0.01) + out.backward() + adam.minimize(loss) + adam.clear_grad() + +.. py:method:: clear_grad() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + + +清除需要优化的参数的梯度。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + optimizer = paddle.optimizer.Adam(learning_rate=0.02, + parameters=linear.parameters()) + out = linear(a) + out.backward() + optimizer.step() + optimizer.clear_grad() + +.. py:method:: set_lr(value) + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +手动设置当前 ``optimizer`` 的学习率。当使用_LRScheduler时，无法使用该API手动设置学习率，因为这将导致冲突。 + +参数： + value (float) - 需要设置的学习率的值。 + +返回：None + +**代码示例** + +.. code-block:: python + + import paddle + paddle.disable_static() + linear = paddle.nn.Linear(10, 10) + + adam = paddle.optimizer.Adam(0.1, parameters=linear.parameters()) + + # set learning rate manually by python float value + lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] + for i in range(5): + adam.set_lr(lr_list[i]) + lr = adam.get_lr() + print("current lr is {}".format(lr)) + # Print: + # current lr is 0.2 + # current lr is 0.3 + # current lr is 0.4 + # current lr is 0.5 + # current lr is 0.6 + +.. py:method:: get_lr() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +获取当前步骤的学习率。当不使用_LRScheduler时，每次调用的返回值都相同，否则返回当前步骤的学习率。 + +返回：float，当前步骤的学习率。 + + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + # example1: _LRScheduler is not used, return value is all the same + paddle.disable_static() + emb = paddle.nn.Embedding(10, 10, sparse=False) + adam = paddle.optimizer.Adam(0.001, parameters = emb.parameters()) + lr = adam.get_lr() + print(lr) # 0.001 + + # example2: PiecewiseLR is used, return the step learning rate + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.reduce_mean(out) + + bd = [2, 4, 6, 8] + value = [0.2, 0.4, 0.6, 0.8, 1.0] + scheduler = paddle.optimizer.PiecewiseLR(bd, value, 0) + adam = paddle.optimizer.Adam(scheduler, + parameters=linear.parameters()) + + # first step: learning rate is 0.2 + np.allclose(adam.get_lr(), 0.2, rtol=1e-06, atol=0.0) # True + + # learning rate for different steps + ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] + for i in range(12): + adam.step() + lr = adam.get_lr() + scheduler.step() + np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True diff --git a/doc/paddle/api/paddle/optimizer/Adamax_cn.rst b/doc/paddle/api/paddle/optimizer/Adamax_cn.rst index 0413d5b109548833548752b8b9e22934633e5d42..b38c446571272905ab42e25ce18a463846c300cf 100644 --- a/doc/paddle/api/paddle/optimizer/Adamax_cn.rst +++ b/doc/paddle/api/paddle/optimizer/Adamax_cn.rst @@ -1,17 +1,242 @@ -.. _cn_api_fluid_optimizer_Adamax: +.. _cn_api_paddle_optimizer_Adamax: Adamax ------------------------------- -.. py:attribute:: paddle.fluid.optimizer.Adamax +.. py:class:: paddle.optimizer.Adamax(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, name=None) -``AdamaxOptimizer`` 的别名 +Adamax优化器是参考 `Adam论文 `_ 第7节Adamax优化相关内容所实现的。Adamax算法是基于无穷大范数的 `Adam `_ 算法的一个变种，使学习率更新的算法更加稳定和简单。 +其参数更新的计算公式如下: +.. math:: + \\t = t + 1 +.. math:: + moment\_out=\beta_1∗moment+(1−\beta_1)∗grad +.. math:: + inf\_norm\_out=\max{(\beta_2∗inf\_norm+\epsilon, \left|grad\right|)} +.. math:: + learning\_rate=\frac{learning\_rate}{1-\beta_1^t} +.. math:: + param\_out=param−learning\_rate*\frac{moment\_out}{inf\_norm\_out}\\ +相关论文：`Adam: A Method for Stochastic Optimization `_ +论文中没有 ``epsilon`` 参数。但是，为了保持数值稳定性， 避免除0错误， 此处增加了这个参数。 +参数： + - **learning_rate** (float|_LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler类，默认值为0.001 + - **beta1** (float, 可选) - 一阶矩估计的指数衰减率，默认值为0.9 + - **beta2** (float, 可选) - 二阶矩估计的指数衰减率，默认值为0.999 + - **epsilon** (float, 可选) - 保持数值稳定性的短浮点类型值，默认值为1e-08 + - **parameters** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 + - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是float类型的L2正则化系数或者正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 + :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； + 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 + - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 + 默认值为None，此时将不进行梯度裁剪。 + - **name** (str, 可选)- 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None +.. note:: + 目前 ``Adamax`` 不支持 Sparse Parameter Optimization（稀疏参数优化）。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + adam = paddle.optimizer.Adamax(learning_rate=0.1, + parameters=linear.parameters()) + out.backward() + adam.step() + adam.clear_grad() + + +.. py:method:: step() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +执行一次优化器并进行参数更新。 + +返回：None。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + adam = paddle.optimizer.Adam(learning_rate = 0.01, + parameters = linear.parameters()) + out = linear(a) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: minimize(loss, startup_program=None, parameters=None, no_grad_set=None) + +为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameters中的Parameters，最小化网络损失值loss。 + +参数： + - **loss** (Tensor) – 需要最小化的损失值变量 + - **startup_program** (Program, 可选) – 用于初始化parameters中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` + - **parameters** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter + - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成集合，默认值为None + +返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。在静态图模式下，该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.Adamax(learning_rate=0.1, + parameters=linear.parameters(), + weight_decay=0.01) + out.backward() + adam.minimize(loss) + adam.clear_grad() + + +.. py:method:: clear_grad() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + + +清除需要优化的参数的梯度。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + optimizer = paddle.optimizer.Adamax(learning_rate=0.02, + parameters=linear.parameters()) + out = linear(a) + out.backward() + optimizer.step() + optimizer.clear_grad() + +.. py:method:: set_lr(value) + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +手动设置当前 ``optimizer`` 的学习率。当使用_LRScheduler时，无法使用该API手动设置学习率，因为这将导致冲突。 + +参数： + value (float) - 需要设置的学习率的值。 + +返回：None + +**代码示例** + +.. code-block:: python + + import paddle + paddle.disable_static() + linear = paddle.nn.Linear(10, 10) + + adam = paddle.optimizer.Adamax(0.1, parameters=linear.parameters()) + + # set learning rate manually by python float value + lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] + for i in range(5): + adam.set_lr(lr_list[i]) + lr = adam.get_lr() + print("current lr is {}".format(lr)) + # Print: + # current lr is 0.2 + # current lr is 0.3 + # current lr is 0.4 + # current lr is 0.5 + # current lr is 0.6 + +.. py:method:: get_lr() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +获取当前步骤的学习率。当不使用_LRScheduler时，每次调用的返回值都相同，否则返回当前步骤的学习率。 + +返回：float，当前步骤的学习率。 + + +**代码示例** + +.. code-block:: python + + + import numpy as np + import paddle + # example1: _LRScheduler is not used, return value is all the same + paddle.disable_static() + emb = paddle.nn.Embedding(10, 10, sparse=False) + adam = paddle.optimizer.Adamax(0.001, parameters = emb.parameters()) + lr = adam.get_lr() + print(lr) # 0.001 + + # example2: PiecewiseLR is used, return the step learning rate + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.reduce_mean(out) + + bd = [2, 4, 6, 8] + value = [0.2, 0.4, 0.6, 0.8, 1.0] + scheduler = paddle.optimizer.PiecewiseLR(bd, value, 0) + adam = paddle.optimizer.Adamax(scheduler, + parameters=linear.parameters()) + + # first step: learning rate is 0.2 + np.allclose(adam.get_lr(), 0.2, rtol=1e-06, atol=0.0) # True + + # learning rate for different steps + ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] + for i in range(12): + adam.step() + lr = adam.get_lr() + scheduler.step() + np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True diff --git a/doc/paddle/api/paddle/optimizer/CosineAnnealingLR_cn.rst b/doc/paddle/api/paddle/optimizer/CosineAnnealingLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..177ee846f284d232209f27cfd35a51938a527a5c --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/CosineAnnealingLR_cn.rst @@ -0,0 +1,100 @@ +.. _cn_api_paddle_optimizer_CosineAnnealingLR: + +CosineAnnealingLR +----------------------------------- + +.. py:class:: paddle.optimizer.lr_scheduler.CosineAnnealingLR(learning_rate, T_max, eta_min=0, last_epoch=-1, verbose=False) + +该接口使用 ``cosine annealing`` 方式来动态调整学习率。 + +.. math:: + \begin{aligned} + \eta_t & = \eta_{min} + \frac{1}{2}(\eta_{max} - \eta_{min})\left(1 + + \cos\left(\frac{T_{cur}}{T_{max}}\pi\right)\right), + & T_{cur} \neq (2k+1)T_{max}; \\ + \eta_{t+1} & = \eta_{t} + \frac{1}{2}(\eta_{max} - \eta_{min}) + \left(1 - \cos\left(\frac{1}{T_{max}}\pi\right)\right), + & T_{cur} = (2k+1)T_{max}. + \end{aligned} + + +:math:`\eta_{max}` 的初始值为 ``learning_rate``, :math:`T_{cur}` 是SGDR（重启训练SGD）训练过程中的当前训练轮数。SGDR的训练方法可以参考文档 `SGDR: Stochastic Gradient Descent with Warm Restarts `_. +这里只是实现了 ``cosine annealing`` 动态学习率，热启训练部分没有实现。 + + +参数 +::::::::: + - **learning_rate** （float）：初始学习率，可以是Python的float。 + - **T_max** （float|int）：训练的上限轮数，是学习率衰减周期的一半。 + - **eta_min** （float|int, 可选）：学习率的下限，即公式中的 :math:`\eta_{min}` 。默认值为0。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: + 返回计算CosineAnnealingLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default imperative mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.CosineAnnealingLR(learning_rate=0.5, T_max=10, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.CosineAnnealingLR(learning_rate=0.5, T_max=10, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + diff --git a/doc/paddle/api/paddle/optimizer/ExponentialLR_cn.rst b/doc/paddle/api/paddle/optimizer/ExponentialLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..7360bd3f3c758f7f5a4c71f73b1e6ef12cfcae14 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/ExponentialLR_cn.rst @@ -0,0 +1,92 @@ +.. _cn_api_paddle_optimizer_ExponentialLR: + +ExponentialLR +----------------------------------- + +.. py:class:: paddle.optimizer.lr_scheduler.ExponentialLR(learning_rate, gamma, last_epoch=-1, verbose=False) + +该接口提供一种学习率按指数函数衰减的功能。 + +衰减函数可以用以下公式表示： + +.. math:: + + new\_learning\_rate = last\_learning\_rate * gamma + +参数 +::::::::: + - **learning_rate** （float） - 初始学习率，数据类型为Python float。 + - **gamma** （float）：衰减率，new_lr = origin_lr * gamma。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率 。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: +返回计算ExponentialLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.ExponentialLR(learning_rate=0.5, gamma=0.9, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.ExponentialLR(learning_rate=0.5, gamma=0.9, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + + diff --git a/doc/paddle/api/paddle/optimizer/InverseTimeLR_cn.rst b/doc/paddle/api/paddle/optimizer/InverseTimeLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..7738cf5c504c5533ae9a69ebf262b9c18195c27b --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/InverseTimeLR_cn.rst @@ -0,0 +1,94 @@ +.. _cn_api_paddle_optimizer_InverseTimeLR: + +InverseTimeLR +------------------------------- + + +.. py:class:: paddle.optimizer.lr_scheduler.InverseTimeLR(learning_rate, gamma, last_epoch=-1, verbose=False) + + +该接口提供反时限学习率衰减的功能。 + +反时限学习率衰减计算方式如下。 + +当staircase为False时，计算公式为： + +.. math:: + + new\_learning\_rate = \\frac{learning\_rate}{1 + gamma * epoch} + + +参数 +::::::::: + - **learning_rate** （float） - 初始学习率，数据类型为Python float。 + - **gamma** （float）：衰减率，new_lr = origin_lr * gamma。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: +返回计算InverseTimeLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.InverseTimeLR(learning_rate=0.5, gamma=0.1, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.InverseTimeLR(learning_rate=0.5, gamma=0.1, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 diff --git a/doc/paddle/api/paddle/optimizer/LambdaLR_cn.rst b/doc/paddle/api/paddle/optimizer/LambdaLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..5ae95b411a617ea8b6b41e5042a96ad88ea872be --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/LambdaLR_cn.rst @@ -0,0 +1,95 @@ +.. _cn_api_paddle_optimizer_LambdaLR: + +LambdaLR +----------------------------------- + +.. py:class:: paddle.optimizer.lr_scheduler.LambdaLR(learning_rate, lr_lambda, last_epoch=-1, verbose=False) + +该接口提供 ``lambda`` 函数设置学习率的功能。 ``lr_lambda`` 为一个 ``lambda`` 函数，其通过 ``epoch`` 计算出一个因子，该因子会乘以初始学习率。。 + +衰减过程可以参考以下代码： + +.. code-block:: python + + learning_rate = 0.5 # init learning_rate + lr_lambda = lambda epoch: 0.95 ** epoch + learning_rate = 0.5 # epoch 0 + learning_rate = 0.475 # epoch 1 + learning_rate = 0.45125 # epoch 2 + + +参数 +::::::::: + - **learning_rate** （float） - 初始学习率，数据类型为Python float。 + - **lr_lambda** （function）：lr_lambda 为一个lambda函数，其通过 epoch 计算出一个因子，该因子会乘以初始学习率。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率 。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: + 返回计算LambdaLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.LambdaLR(learning_rate=0.5, lr_lambda=lambda x:0.95**x, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.LambdaLR(learning_rate=0.5, lr_lambda=lambda x:0.95**x, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + diff --git a/doc/paddle/api/paddle/optimizer/LinearLrWarmup_cn.rst b/doc/paddle/api/paddle/optimizer/LinearLrWarmup_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a998567058693d62903618246658883b2f9310d9 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/LinearLrWarmup_cn.rst @@ -0,0 +1,105 @@ +.. _cn_api_paddle_optimizer_LinearLrWarmup: + +LinearLrWarmup +----------------------------------- + +.. py:class:: paddle.optimizer.lr_scheduler.LinearLrWarmup(learing_rate, warmup_steps, start_lr, end_lr, last_epoch=-1, verbose=False) + +该接口提供一种学习率优化策略-线性学习率热身(warm up)对学习率进行初步调整。在正常调整学习率之前，先逐步增大学习率。 + +当训练步数小于热身步数（warmup_steps）时，学习率lr按如下方式更新： + +.. code-block:: text + + linear_step = end_lr - start_lr + lr = start_lr + linear_step * (epoch / warmup_steps) + +当训练步数大于等于热身步数（warmup_steps）时，学习率lr为： + +.. code-block:: text + + lr = learning_rate + +其中learning_rate为热身之后的学习率。 + +参数 +::::::::: + - **learning rate** （float|_LRScheduler）：热启训练之后的学习率，可以是Python的float或_LRScheduler子类。 + - **warmup_steps** （int）：进行warm up过程的步数。 + - **start_lr** （float）：warm up的起始学习率。 + - **end_lr** （float）：warm up的最终学习率。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率 。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + + +返回 +::::::::: +返回计算LinearLrWarmup的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.LinearLrWarmup( + learning_rate=0.5, warmup_steps=20, start_lr=0, end_lr=0.5, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.LinearLrWarmup( + learning_rate=0.5, warmup_steps=20, start_lr=0, end_lr=0.5, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + + diff --git a/doc/paddle/api/paddle/optimizer/MomentumOptimizer_cn.rst b/doc/paddle/api/paddle/optimizer/MomentumOptimizer_cn.rst deleted file mode 100644 index c2c39c5a8fad49c25a80ba2668eb0a332698dda7..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/optimizer/MomentumOptimizer_cn.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. _cn_api_fluid_optimizer_MomentumOptimizer: - -MomentumOptimizer -------------------------------- - -.. py:class:: paddle.fluid.optimizer.MomentumOptimizer(learning_rate, momentum, parameter_list=None, use_nesterov=False, regularization=None, grad_clip=None, name=None) - - - - -该接口实现含有速度状态的Simple Momentum 优化器 - -该优化器含有牛顿动量标志，公式更新如下： - -.. math:: - & velocity = mu * velocity + gradient\\ - & if (use\_nesterov):\\ - &\quad param = param - (gradient + mu * velocity) * learning\_rate\\ - & else:\\&\quad param = param - learning\_rate * velocity - -参数： - - **learning_rate** (float|Variable) - 学习率，用于参数更新。作为数据参数，可以是浮点型值或含有一个浮点型值的变量。 - - **momentum** (float) - 动量因子。 - - **parameter_list** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 - - **use_nesterov** (bool，可选) - 赋能牛顿动量，默认值False。 - - **regularization** (WeightDecayRegularizer，可选) - 正则化方法。支持两种正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 - :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； - 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 - - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 - 默认值为None，此时将不进行梯度裁剪。 - - **name** (str, 可选) - 可选的名称前缀，一般无需设置，默认值为None。 - -**代码示例**： - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - place = fluid.CPUPlace() - main = fluid.Program() - with fluid.program_guard(main): - x = fluid.layers.data(name='x', shape=[13], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_cost = fluid.layers.mean(cost) - - moment_optimizer = fluid.optimizer.MomentumOptimizer(learning_rate=0.001, momentum=0.9) - moment_optimizer.minimize(avg_cost) - - fetch_list = [avg_cost] - train_reader = paddle.batch( - paddle.dataset.uci_housing.train(), batch_size=1) - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - for data in train_reader(): - exe.run(main, feed=feeder.feed(data), fetch_list=fetch_list) - - - -.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None) - -为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameter_list中的Parameters，最小化网络损失值loss。 - -参数： - - **loss** (Variable) – 需要最小化的损失值变量 - - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` - - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter - - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None - -返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 - -返回类型： tuple - -**代码示例**： - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - place = fluid.CPUPlace() - main = fluid.Program() - with fluid.program_guard(main): - x = fluid.layers.data(name='x', shape=[13], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='float32') - y_predict = fluid.layers.fc(input=x, size=1, act=None) - cost = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_cost = fluid.layers.mean(cost) - - moment_optimizer = fluid.optimizer.MomentumOptimizer(learning_rate=0.001, momentum=0.9) - moment_optimizer.minimize(avg_cost) - - fetch_list = [avg_cost] - train_reader = paddle.batch( - paddle.dataset.uci_housing.train(), batch_size=1) - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - for data in train_reader(): - exe.run(main, feed=feeder.feed(data), fetch_list=fetch_list) - - - -.. py:method:: clear_gradients() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - - -清除需要优化的参数的梯度。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - with fluid.dygraph.guard(): - value = np.arange(26).reshape(2, 13).astype("float32") - a = fluid.dygraph.to_variable(value) - linear = fluid.Linear(13, 5, dtype="float32") - optimizer = fluid.optimizer.MomentumOptimizer(learning_rate=0.001, momentum=0.9, - parameter_list=linear.parameters()) - out = linear(a) - out.backward() - optimizer.minimize(out) - optimizer.clear_gradients() - - -.. py:method:: set_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -手动设置当前 ``optimizer`` 的学习率。当使用LearningRateDecay时，无法使用该API手动设置学习率，因为这将导致冲突。 - -参数： - value (float|Variable) - 需要设置的学习率的值。 - -返回：无 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - with fluid.dygraph.guard(): - linear = fluid.dygraph.nn.Linear(10, 10) - adam = fluid.optimizer.Adam(0.1, parameter_list=linear.parameters()) - # 通过Python float数值手动设置学习率 - lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] - for i in range(5): - adam.set_lr(lr_list[i]) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.2 - # current lr is 0.3 - # current lr is 0.4 - # current lr is 0.5 - # current lr is 0.6 - - - # 通过 框架的Variable 设置学习率 - lr_var = fluid.layers.create_global_var(shape=[1], value=0.7, dtype='float32') - adam.set_lr(lr_var) - print("current lr is {}".format(adam.current_step_lr())) - # 打印结果: - # current lr is 0.7 - - - -.. py:method:: current_step_lr() - -**注意：** - - **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** - -获取当前步骤的学习率。当不使用LearningRateDecay时，每次调用的返回值都相同，否则返回当前步骤的学习率。 - -返回：当前步骤的学习率。 - -返回类型：float - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # example1: LearningRateDecay is not used, return value is all the same - with fluid.dygraph.guard(): - emb = fluid.dygraph.Embedding([10, 10]) - adam = fluid.optimizer.Adam(0.001, parameter_list = emb.parameters()) - lr = adam.current_step_lr() - print(lr) # 0.001 - - # example2: PiecewiseDecay is used, return the step learning rate - with fluid.dygraph.guard(): - inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") - linear = fluid.dygraph.nn.Linear(10, 10) - inp = fluid.dygraph.to_variable(inp) - out = linear(inp) - loss = fluid.layers.reduce_mean(out) - - bd = [2, 4, 6, 8] - value = [0.2, 0.4, 0.6, 0.8, 1.0] - adam = fluid.optimizer.Adam(fluid.dygraph.PiecewiseDecay(bd, value, 0), - parameter_list=linear.parameters()) - - # first step: learning rate is 0.2 - np.allclose(adam.current_step_lr(), 0.2, rtol=1e-06, atol=0.0) # True - - # learning rate for different steps - ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] - for i in range(12): - adam.minimize(loss) - lr = adam.current_step_lr() - np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True - diff --git a/doc/paddle/api/paddle/optimizer/MultiStepLR_cn.rst b/doc/paddle/api/paddle/optimizer/MultiStepLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e424b3153122a05f63202c5559d0ecd0f3825096 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/MultiStepLR_cn.rst @@ -0,0 +1,100 @@ +.. _cn_api_paddle_optimizer_MultiStepLR: + +MultiStepLR +----------------------------------- + +.. py:class:: paddle.optimizer.lr_scheduler.MultiStepLR(learning_rate, milestones, gamma=0.1, last_epoch=-1, verbose=False) + +该接口提供一种学习率按指定轮数衰减的功能。 + +衰减过程可以参考以下代码： + +.. code-block:: text + + learning_rate = 0.5 + milestones = [30, 50] + gamma = 0.1 + if epoch < 30: + learning_rate = 0.5 + elif epoch < 50: + learning_rate = 0.05 # 0.5 * 0.1 + else: + learning_rate = 0.005 # 0.05 * 0.1 + +参数 +::::::::: + - **learning_rate** （float） - 初始学习率，数据类型为Python float。 + - **milestones** ：（list）：轮数下标列表。必须递增。 + - **gamma** （float，可选）：衰减率，new_lr = origin_lr * gamma, 衰减率必须小于等于1.0，默认值为0.1。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率 。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + + +返回 +::::::::: +返回计算MultiStepLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.MultiStepLR(learning_rate=0.5, milestones=[2, 4, 6], gamma=0.8, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.MultiStepLR(learning_rate=0.5, milestones=[2, 4, 6], gamma=0.8, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + diff --git a/doc/paddle/api/paddle/optimizer/NaturalExpLR_cn.rst b/doc/paddle/api/paddle/optimizer/NaturalExpLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c89cd03a7aee7356d7315518c69c59d4c87793aa --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/NaturalExpLR_cn.rst @@ -0,0 +1,91 @@ +.. _cn_api_paddle_optimizer_NaturalExpLR: + +NaturalExpLR +------------------------------- + + +.. py:class:: paddle.optimizer.lr_scheduler.NaturalExpLR(learning_rate, gama, last_epoch=-1, verbose=False) + +该接口提供按自然指数衰减学习率的功能。 + +自然指数衰减的计算方式如下。 + +.. math:: + + decayed\_learning\_rate = learning\_rate * e^{y} + +参数 +::::::::: + - **learning_rate** （float） - 初始学习率，数据类型为Python float。 + - **gamma** （float）：衰减率。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: +返回计算NaturalExpLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.NaturalExpLR(learning_rate=0.5, gamma=0.1, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.NaturalExpLR(learning_rate=0.5, gamma=0.1, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + diff --git a/doc/paddle/api/paddle/optimizer/NoamLR_cn.rst b/doc/paddle/api/paddle/optimizer/NoamLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..eadb423134cadd459d1719b658756c1bb2cfcfb3 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/NoamLR_cn.rst @@ -0,0 +1,98 @@ +.. _cn_api_paddle_optimizer_NoamLR: + +NoamLR +------------------------------- + + +.. py:class:: paddle.optimizer.lr_scheduler.NoamLR(d_model, warmup_steps, learning_rate=1.0, last_epoch=-1, verbose=False) + + +该接口提供Noam衰减学习率的功能。 + +Noam衰减的计算方式如下。 + +.. math:: + + decayed\_learning\_rate = learning\_rate * d_{model}^{-0.5} * min(epoch^{-0.5}, epoch * warmup\_steps^{-1.5}) + +关于Noam衰减的更多细节请参考 `attention is all you need `_ + +参数 +::::::::: + - **d$_{model}$** （int） - 模型的输入、输出向量特征维度，为超参数。数据类型为Python int。 + - **warmup_steps** （int） - 预热步数，为超参数。数据类型为Python int。 + - **learning_rate** （float） - 初始学习率，数据类型为Python float。默认值为1.0。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: +返回计算NoamLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.NoamLR(d_model=0.01, warmup_steps=100, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.NoamLR(d_model=0.01, warmup_steps=100, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + + + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + + diff --git a/doc/paddle/api/paddle/optimizer/Optimizer_cn.rst b/doc/paddle/api/paddle/optimizer/Optimizer_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..5aa31be296502db20d199843a4613537185caa1d --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/Optimizer_cn.rst @@ -0,0 +1,220 @@ +.. _cn_api_paddle_optimizer_Optimizer: + +Optimizer +------------------------------- + +.. py:class:: paddle.optimizer.Optimizer(learning_rate=0.001, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, name=None) + + + +优化器的基类。 + +参数: + - **learning_rate** (float|_LRSeduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler类，默认值为0.001 + - **parameters** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 + - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是float类型的L2正则化系数或者正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 + :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； + 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 + - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 + 默认值为None，此时将不进行梯度裁剪。 + - **name** (str, 可选)- 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None + + +**代码示例** + +.. code-block:: python + + #以子类Adam为例 + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + adam = paddle.optimizer.Adam(learning_rate=0.1, + parameters=linear.parameters()) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: step() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +执行一次优化器并进行参数更新。 + +返回：None。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + # This can be any optimizer supported by dygraph. + adam = paddle.optimizer.Adam(learning_rate = 0.01, + parameters = linear.parameters()) + out = linear(a) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: minimize(loss, startup_program=None, parameters=None, no_grad_set=None) + +为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameters中的Parameters，最小化网络损失值loss。 + +参数： + - **loss** (Tensor) – 需要最小化的损失值变量 + - **startup_program** (Program, 可选) – 用于初始化parameters中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` + - **parameters** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter + - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None + +返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。在静态图模式下，该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.Adam(learning_rate=0.1, + parameters=linear.parameters(), + weight_decay=0.01) + out.backward() + adam.minimize(loss) + adam.clear_grad() + +.. py:method:: clear_grad() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + + +清除需要优化的参数的梯度。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + optimizer = paddle.optimizer.Adam(learning_rate=0.02, + parameters=linear.parameters()) + out = linear(a) + out.backward() + optimizer.step() + optimizer.clear_grad() + +.. py:method:: set_lr(value) + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +手动设置当前 ``optimizer`` 的学习率。当使用_LRScheduler时，无法使用该API手动设置学习率，因为这将导致冲突。 + +参数： + value (float) - 需要设置的学习率的值。 + +返回：None + +**代码示例** + +.. code-block:: python + + import paddle + paddle.disable_static() + linear = paddle.nn.Linear(10, 10) + + adam = paddle.optimizer.Adam(0.1, parameters=linear.parameters()) + + # set learning rate manually by python float value + lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] + for i in range(5): + adam.set_lr(lr_list[i]) + lr = adam.get_lr() + print("current lr is {}".format(lr)) + # Print: + # current lr is 0.2 + # current lr is 0.3 + # current lr is 0.4 + # current lr is 0.5 + # current lr is 0.6 + +.. py:method:: get_lr() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +获取当前步骤的学习率。当不使用_LRScheduler时，每次调用的返回值都相同，否则返回当前步骤的学习率。 + +返回：float，当前步骤的学习率。 + + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + # example1: _LRScheduler is not used, return value is all the same + paddle.disable_static() + emb = paddle.nn.Embedding(10, 10, sparse=False) + adam = paddle.optimizer.Adam(0.001, parameters = emb.parameters()) + lr = adam.get_lr() + print(lr) # 0.001 + + # example2: PiecewiseLR is used, return the step learning rate + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.reduce_mean(out) + + bd = [2, 4, 6, 8] + value = [0.2, 0.4, 0.6, 0.8, 1.0] + scheduler = paddle.optimizer.PiecewiseLR(bd, value, 0) + adam = paddle.optimizer.Adam(scheduler, + parameters=linear.parameters()) + + # first step: learning rate is 0.2 + np.allclose(adam.get_lr(), 0.2, rtol=1e-06, atol=0.0) # True + + # learning rate for different steps + ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] + for i in range(12): + adam.step() + lr = adam.get_lr() + scheduler.step() + np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True + diff --git a/doc/paddle/api/paddle/optimizer/PiecewiseLR_cn.rst b/doc/paddle/api/paddle/optimizer/PiecewiseLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..5f22bd57cf2646c2246b9238e28ffb548ab819db --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/PiecewiseLR_cn.rst @@ -0,0 +1,95 @@ +.. _cn_api_paddle_optimizer_PiecewiseLR: + +PiecewiseLR +------------------------------- + + +.. py:class:: paddle.optimizer.lr_scheduler.PiecewiseLR(boundaries, values, last_epoch=-1, verbose=False) + + +该接口提供对初始学习率进行分段(piecewise)常数衰减的功能。 + +分段常数衰减的过程举例描述如下。 + +.. code-block:: text + + 例如，设定的boundaries列表为[100, 200]，候选学习率常量列表values为[1.0, 0.5, 0.1]，则： + 1、在当前训练步数epoch小于100步，学习率值为1.0。 + 2、在当前训练步数epoch大于或等于100步，并且小于200步时，学习率值为0.5。 + 3、在当前训练步数epoch大于或等于200步时，学习率值为0.1。 + + +参数 +::::::::: + - **boundaries** （list）：指定衰减的步数边界。列表的数据元素为Python int类型。 + - **values** （list） ：备选学习率列表。数据元素类型为Python float的列表。与边界值列表有对应的关系。 + - **last_epoch** （int，可选）：上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率 。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + +返回 +::::::::: +返回计算PiecewiseLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.PiecewiseLR(boundaries=[3, 6, 9], values=[0.1, 0.2, 0.3, 0.4], verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.PiecewiseLR(boundaries=[3, 6, 9], values=[0.1, 0.2, 0.3, 0.4], verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 diff --git a/doc/paddle/api/paddle/optimizer/RMSProp_cn.rst b/doc/paddle/api/paddle/optimizer/RMSProp_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..2439a95494df7f5199e877cf9f66841dba5fc8a0 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/RMSProp_cn.rst @@ -0,0 +1,251 @@ +.. _cn_api_paddle_optimizer_RMSProp: + +RMSProp +------------------------------- + +.. py:class:: paddle.optimizer.RMSProp(learning_rate, rho=0.95, epsilon=1e-06, momentum=0.0, centered=False, parameters=None, weight_decay=None, grad_clip=None, name=None) + + + + +该接口实现均方根传播（RMSProp）法，是一种未发表的,自适应学习率的方法。原演示幻灯片中提出了RMSProp：[http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf]中的第29张。等式如下所示： + +.. math:: + r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ + w & = w - \frac{\eta} {\sqrt{r(w,t) + \epsilon}} \nabla Q_{i}(w) + +第一个等式计算每个权重平方梯度的移动平均值，然后将梯度除以 :math:`sqrtv（w，t）` 。 + +.. math:: + r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ + v(w, t) & = \beta v(w, t-1) +\frac{\eta} {\sqrt{r(w,t) +\epsilon}} \nabla Q_{i}(w)\\ + w & = w - v(w, t) + +如果居中为真： + +.. math:: + r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ + g(w, t) & = \rho g(w, t-1) + (1 -\rho)\nabla Q_{i}(w)\\ + v(w, t) & = \beta v(w, t-1) + \frac{\eta} {\sqrt{r(w,t) - (g(w, t))^2 +\epsilon}} \nabla Q_{i}(w)\\ + w & = w - v(w, t) + +其中， :math:`ρ` 是超参数，典型值为0.9,0.95等。 :math:`beta` 是动量术语。 :math:`epsilon` 是一个平滑项，用于避免除零，通常设置在1e-4到1e-8的范围内。 + +参数： + - **learning_rate** （float） - 全局学习率。 + - **rho** （float，可选） - rho是等式中的 :math:`rho` ，默认值0.95。 + - **epsilon** （float，可选） - 等式中的epsilon是平滑项，避免被零除，默认值1e-6。 + - **momentum** （float，可选） - 方程中的β是动量项，默认值0.0。 + - **centered** （bool，可选） - 如果为True，则通过梯度的估计方差,对梯度进行归一化；如果False，则由未centered的第二个moment归一化。将此设置为True有助于模型训练，但会消耗额外计算和内存资源。默认为False。 + - **parameters** (list, 可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。 + - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是float类型的L2正则化系数或者正则化策略: :ref:`cn_api_fluid_regularizer_L1Decay` 、 + :ref:`cn_api_fluid_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_fluid_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； + 如果没有在 :ref:`cn_api_fluid_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。 + - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。 + 默认值为None，此时将不进行梯度裁剪。 + - **name** (str, 可选) - 可选的名称前缀，一般无需设置，默认值为None。 + +抛出异常: + - ``ValueError`` -如果 ``learning_rate`` ， ``rho`` ， ``epsilon`` ， ``momentum`` 为None。 + +**示例代码** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.RMSProp(learning_rate=0.1, + parameters=linear.parameters(), + weight_decay=0.01) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: step() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +执行一次优化器并进行参数更新。 + +返回：None。 + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + adam = paddle.optimizer.RMSProp(learning_rate = 0.01, + parameters = linear.parameters()) + out = linear(a) + out.backward() + adam.step() + adam.clear_grad() + +.. py:method:: minimize(loss, startup_program=None, parameters=None, no_grad_set=None) + +为网络添加反向计算过程，并根据反向计算所得的梯度，更新parameters中的Parameters，最小化网络损失值loss。 + +参数： + - **loss** (Tensor) – 需要最小化的损失值变量 + - **startup_program** (Program, 可选) – 用于初始化parameters中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` + - **parameters** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter + - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None + +返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。在静态图模式下，该返回值可以加入到 ``Executor.run()`` 接口的 ``fetch_list`` 参数中，若加入，则会重写 ``use_prune`` 参数为True，并根据 ``feed`` 和 ``fetch_list`` 进行剪枝，详见 ``Executor`` 的文档。 + + +**示例代码** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.mean(out) + + beta1 = paddle.to_tensor([0.9], dtype="float32") + beta2 = paddle.to_tensor([0.99], dtype="float32") + + adam = paddle.optimizer.RMSProp(learning_rate=0.1, + parameters=linear.parameters(), + weight_decay=0.01) + out.backward() + adam.minimize(loss) + adam.clear_grad() + +.. py:method:: clear_gradients() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + + +清除需要优化的参数的梯度。 + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + value = np.arange(26).reshape(2, 13).astype("float32") + a = paddle.to_tensor(value) + linear = paddle.nn.Linear(13, 5) + optimizer = paddle.optimizer.RMSProp(learning_rate=0.02, + parameters=linear.parameters()) + out = linear(a) + out.backward() + optimizer.step() + optimizer.clear_gradients() + +.. py:method:: set_lr(value) + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +手动设置当前 ``optimizer`` 的学习率。当使用_LRScheduler时，无法使用该API手动设置学习率，因为这将导致冲突。 + +参数： + value (float) - 需要设置的学习率的值。 + +返回：None + +**代码示例** + +.. code-block:: python + + + import paddle + paddle.disable_static() + linear = paddle.nn.Linear(10, 10) + + adam = paddle.optimizer.RMSProp(0.1, parameters=linear.parameters()) + + # set learning rate manually by python float value + lr_list = [0.2, 0.3, 0.4, 0.5, 0.6] + for i in range(5): + adam.set_lr(lr_list[i]) + lr = adam.get_lr() + print("current lr is {}".format(lr)) + # Print: + # current lr is 0.2 + # current lr is 0.3 + # current lr is 0.4 + # current lr is 0.5 + # current lr is 0.6 + +.. py:method:: get_lr() + +**注意：** + + **1. 该API只在** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **模式下生效** + +获取当前步骤的学习率。当不使用_LRScheduler时，每次调用的返回值都相同，否则返回当前步骤的学习率。 + +返回：float，当前步骤的学习率。 + + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + # example1: _LRScheduler is not used, return value is all the same + paddle.disable_static() + emb = paddle.nn.Embedding(10, 10, sparse=False) + adam = paddle.optimizer.RMSProp(0.001, parameters = emb.parameters()) + lr = adam.get_lr() + print(lr) # 0.001 + + # example2: PiecewiseDecay is used, return the step learning rate + paddle.disable_static() + inp = np.random.uniform(-0.1, 0.1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + inp = paddle.to_tensor(inp) + out = linear(inp) + loss = paddle.reduce_mean(out) + + bd = [2, 4, 6, 8] + value = [0.2, 0.4, 0.6, 0.8, 1.0] + scheduler = paddle.optimizer.PiecewiseLR(bd, value, 0) + adam = paddle.optimizer.RMSProp(scheduler, + parameters=linear.parameters()) + + # first step: learning rate is 0.2 + np.allclose(adam.get_lr(), 0.2, rtol=1e-06, atol=0.0) # True + + # learning rate for different steps + ret = [0.2, 0.2, 0.4, 0.4, 0.6, 0.6, 0.8, 0.8, 1.0, 1.0, 1.0, 1.0] + for i in range(12): + adam.step() + lr = adam.get_lr() + scheduler.step() + np.allclose(lr, ret[i], rtol=1e-06, atol=0.0) # True diff --git a/doc/paddle/api/paddle/optimizer/ReduceLROnPlateau_cn.rst b/doc/paddle/api/paddle/optimizer/ReduceLROnPlateau_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..b0a0b75f7b31244421f02cab719a342461a9f7c1 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/ReduceLROnPlateau_cn.rst @@ -0,0 +1,89 @@ +.. _cn_api_fluid_dygraph_ReduceLROnPlateau: + +ReduceLROnPlateau +------------------------------- + +**注意：该API仅支持【动态图】模式** + +.. py:class:: paddle.fluid.dygraph.ReduceLROnPlateau(learning_rate, mode='min', decay_rate=0.1, patience=10, verbose=False, threshold=1e-4, threshold_mode='rel', cooldown=0, min_lr=0, eps=1e-8, dtype='float32') + +该API为 ``loss`` 自适应的学习率衰减策略。默认情况下，当 ``loss`` 停止下降时，降低学习率（如果将 ``mode`` 设置为 `'max'` ，此时判断逻辑相反， ``loss`` 停止上升时降低学习率）。其思想是：一旦模型表现不再提升，将学习率降低2-10倍对模型的训练往往有益。 + +``loss`` 是传入到该类方法 ``step`` 中的参数，其必须是shape为[1]的1-D Tensor。 如果 ``loss`` 停止下降（``mode`` 为 `min` 时）超过 ``patience`` 个epoch，学习率将会减小为 +`learning_rate * decay_rate` 。 + +此外，每降低一次学习率后，将会进入一个时长为 ``cooldown`` 个epoch的冷静期，在冷静期内，将不会监控 ``loss`` 的变化情况，也不会衰减。 +在冷静期之后，会继续监控 ``loss`` 的上升或下降。 + +参数： + - **learning_rate** (Variable|float|int) - 初始学习率。其类型可以是Python的float类型，如果输入int类型则会被转为float类型。其也可以是shape为[1]的 + 1-D Tensor，且相应数据类型必须为 "float32" 或 "float64" 。 + - **mode** (str，可选) - `'min'` 和 `'max'` 之一。通常情况下，为 `'min'` ，此时当 ``loss`` 停止下降时学习率将减小。默认：`'min'` 。 + （注意：仅在特殊用法时，可以将其设置为 `'max'` ，此时判断逻辑相反， ``loss`` 停止上升学习率才减小） + - **decay_rate** (float，可选) - 学习率衰减的比例。`new_lr = origin_lr * decay_rate` ，它是值小于1.0的float型数字，默认: 0.1。 + - **patience** (int，可选) - 当 ``loss`` 连续 ``patience`` 个epoch没有下降(mode: 'min')或上升(mode: 'max')时，学习率才会减小。默认：10。 + - **verbose** (bool，可选) - 如果为 ``True`` ， 会在每次更新optimizer中的learning_rate时，打印信息。默认：``False`` 。 + - **threshold** (float，可选) - ``threshold`` 和 ``threshold_mode`` 两个参数将会决定 ``loss`` 最小变化的阈值。小于该阈值的变化 + 将会被忽视。默认：1e-4。 + - **threshold_mode** (str，可选) - `'rel'` 和 `'abs'` 之一。在 `'rel'` 模式下， ``loss`` 最小变化的阈值是 `last_loss * threshold` ， + 其中 ``last_loss`` 是 ``loss`` 在上个epoch的值。在 `'abs'` 模式下，``loss`` 最小变化的阈值是 `threshold` 。 默认：`'rel'`。 + - **cooldown** (int，可选) - 在学习速率每次减小之后，会进入时长为 ``cooldown`` 个epoch的冷静期。默认：0。 + - **min_lr** (float，可选) - 最小的学习率。减小后的学习率最低下界限。默认：0。 + - **eps** (float，可选) - 如果新旧学习率间的差异小于 ``eps`` ，则不会更新。默认值:1e-8。 + - **dtype** (str，可选) – 学习率值的数据类型，可以为"float32", "float64"。默认："float32"。 + +返回： ``loss`` 自适应的学习率 + +返回类型：Variable + +**代码示例**： + + .. code-block:: python + + import paddle.fluid as fluid + import numpy as np + + with fluid.dygraph.guard(): + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = fluid.dygraph.Linear(10, 10) + input = fluid.dygraph.to_variable(x) + + adam = fluid.optimizer.Adam( + learning_rate = fluid.dygraph.ReduceLROnPlateau( + learning_rate = 1.0, + decay_rate = 0.5, + patience = 5, + verbose = True, + cooldown = 3), + parameter_list = linear.parameters()) + + for epoch in range(10): + total_loss = 0 + for bath_id in range(5): + out = linear(input) + loss = fluid.layers.reduce_mean(out) + total_loss += loss + adam.minimize(loss) + + avg_loss = total_loss/5 + + # 根据传入total_loss，调整学习率 + reduce_lr.step(avg_loss) + lr = adam.current_step_lr() + print("current avg_loss is %s, current lr is %s" % (avg_loss.numpy()[0], lr)) + + + +.. py:method:: step(loss) +需要在每个epoch调用该方法，其根据传入的 ``loss`` 调整optimizer中的学习率，调整后的学习率将会在下一次调用 ``optimizer.minimize`` 时生效。 + +参数： + - **loss** (Variable) - 类型：Variable，shape为[1]的1-D Tensor。将被用来判断是否需要降低学习率。如果 ``loss`` 连续 ``patience`` 个epochs没有下降， + 将会降低学习率。 + +返回： + 无 + +**代码示例**: + + 参照其类中的说明。 diff --git a/doc/paddle/api/paddle/optimizer/StepLR_cn.rst b/doc/paddle/api/paddle/optimizer/StepLR_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..cf4ffa74295a0ca21d5ebf9b905c4c40263edd19 --- /dev/null +++ b/doc/paddle/api/paddle/optimizer/StepLR_cn.rst @@ -0,0 +1,100 @@ +.. _cn_api_paddle_optimizer_StepLR: + +StepLR +----------------------------------- + +.. py:class:: paddle.optimizer.lr_scheduler.StepLR(learning_rate, step_size, gamma=0.1, last_epoch=-1, verbose=False) + +该接口提供一种学习率按指定 `间隔` 轮数衰减的功能。 + +衰减过程可以参考以下代码： + +.. code-block:: text + + learning_rate = 0.5 + step_size = 30 + gamma = 0.1 + if epoch < 30: + learning_rate = 0.5 + elif epoch < 60: + learning_rate = 0.05 # 0.5 * 0.1 + else: + learning_rate = 0.005 # 0.05 * 0.1 + +参数 +::::::::: + - **learning_rate** （float） - 初始学习率，数据类型为Python float。 + - **step_size** ：（int）：学习率衰减轮数间隔。 + - **gamma** （float, 可选）：衰减率，new_lr = origin_lr * gamma, 衰减率必须小于等于1.0，默认值为0.1。 + - **last_epoch** （int，可选）: 上一轮的轮数，重启训练时设置为上一轮的epoch数。默认值为 -1，则为初始学习率 。 + - **verbose** （bool，可选）：如果是 `True` ，则在每一轮更新时在标准输出 `stdout` 输出一条信息。默认值为 ``False`` 。 + + +返回 +::::::::: +返回计算StepLR的可调用对象。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + # train on default dygraph mode + paddle.disable_static() + x = np.random.uniform(-1, 1, [10, 10]).astype("float32") + linear = paddle.nn.Linear(10, 10) + scheduler = paddle.optimizer.lr_scheduler.StepLR(learning_rate=0.5, step_size=5, gamma=0.8, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler, parameter_list=linear.parameters()) + for epoch in range(20): + for batch_id in range(2): + x = paddle.to_tensor(x) + out = linear(x) + loss = paddle.reduce_mean(out) + loss.backward() + sgd.minimize(loss) + linear.clear_gradients() + scheduler.step() + + # train on static mode + paddle.enable_static() + main_prog = paddle.static.Program() + start_prog = paddle.static.Program() + with paddle.static.program_guard(main_prog, start_prog): + x = paddle.static.data(name='x', shape=[None, 4, 5]) + y = paddle.static.data(name='y', shape=[None, 4, 5]) + z = paddle.static.nn.fc(x, 100) + loss = paddle.mean(z) + scheduler = paddle.optimizer.lr_scheduler.StepLR(learning_rate=0.5, step_size=5, gamma=0.8, verbose=True) + sgd = paddle.optimizer.SGD(learning_rate=scheduler) + sgd.minimize(loss) + + exe = paddle.static.Executor() + exe.run(start_prog) + for epoch in range(20): + for batch_id in range(2): + out = exe.run( + main_prog, + feed={ + 'x': np.random.randn(3, 4, 5).astype('float32'), + 'y': np.random.randn(3, 4, 5).astype('float32') + }, + fetch_list=loss.name) + scheduler.step() + +.. py:method:: step(epoch=None) + +step函数需要在优化器的 `step()` 函数之后调用，调用之后将会根据epoch数来更新学习率，更新之后的学习率将会在优化器下一轮更新参数时使用。 + +参数： + - **epoch** （int，可选）- 指定具体的epoch数。默认值None，此时将会从-1自动累加 ``epoch`` 数。 + +返回： + 无。 + +**代码示例** ： + + 参照上述示例代码。 + diff --git a/doc/paddle/api/paddle/static/data_cn.rst b/doc/paddle/api/paddle/static/data_cn.rst deleted file mode 100644 index f250c9438581e2cddaebe4f72c8adb5c6821cdb9..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/static/data_cn.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _cn_api_fluid_data: - -data -------------------------------- - - -.. py:function:: paddle.fluid.data(name, shape, dtype='float32', lod_level=0) - -:api_attr: 声明式编程模式（静态图) -:alias_main: paddle.nn.data -:alias: paddle.nn.data,paddle.nn.input.data -:old_api: paddle.fluid.data - - - -该OP会在全局block中创建变量（Variable），该全局变量可被计算图中的算子（operator）访问。该变量可作为占位符用于数据输入。例如用执行器（Executor）feed数据进该变量 - -注意： - - 不推荐使用 ``paddle.fluid.layers.data`` ，其在之后的版本中会被删除。请使用这个 ``paddle.fluid.data`` 。 - - ``paddle.fluid.layers.data`` 在组网期间会设置创建的变量维度（shape）和数据类型（dtype），但不会检查输入数据的维度和数据类型是否符合要求。 ``paddle.fluid.data`` 会在运行过程中由Executor/ParallelExecutor检查输入数据的维度和数据类型。 - - 如果想输入变长输入，可以使用 ``paddle.fluid.data`` 时将变长维度设为-1，或者直接输入 ``paddle.fluid.layers.data`` 且PaddlePaddle会按具体输入的形状运行。 - - 本API创建的变量默认 ``stop_gradient`` 属性为true，这意味这反向梯度不会被传递过这个数据变量。如果用户想传递反向梯度，可以设置 ``var.stop_gradient = False`` 。 - -参数： - - **name** (str)- 被创建的变量的名字，具体用法请参见 :ref:`api_guide_Name` 。 - - **shape** (list|tuple)- 声明维度信息的list或tuple。 - - **dtype** (np.dtype|VarType|str，可选)- 数据类型，支持bool，float16，float32，float64，int8，int16，int32，int64，uint8。默认值为float32。 - - **lod_level** (int，可选)- LoDTensor变量的LoD level数，LoD level是PaddlePaddle的高级特性，一般任务中不会需要更改此默认值，关于LoD level的详细适用场景和用法请见 :ref:`cn_user_guide_lod_tensor` 。默认值为0。 - -返回：全局变量，可进行数据访问 - -返回类型：Variable - -**代码示例**： - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - - # Creates a variable with fixed size [3, 2, 1] - # User can only feed data of the same shape to x - x = fluid.data(name='x', shape=[3, 2, 1], dtype='float32') - - # Creates a variable with changable batch size -1. - # Users can feed data of any batch size into y, - # but size of each data sample has to be [2, 1] - y = fluid.data(name='y', shape=[-1, 2, 1], dtype='float32') - - z = x + y - - # In this example, we will feed x and y with np-ndarry "1" - # and fetch z, like implementing "1 + 1 = 2" in PaddlePaddle - feed_data = np.ones(shape=[3, 2, 1], dtype=np.float32) - - exe = fluid.Executor(fluid.CPUPlace()) - out = exe.run(fluid.default_main_program(), - feed={ - 'x': feed_data, - 'y': feed_data - }, - fetch_list=[z.name]) - - # np-ndarray of shape=[3, 2, 1], dtype=float32, whose elements are 2 - print(out) - - diff --git a/doc/paddle/api/paddle/static/input/InputSpec_cn.rst b/doc/paddle/api/paddle/static/input/InputSpec_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e431a1a11943ef9b9d98d2f135824f23956a016a --- /dev/null +++ b/doc/paddle/api/paddle/static/input/InputSpec_cn.rst @@ -0,0 +1,126 @@ +.. _cn_api_static_cn_InputSpec: + +InputSpec +------------------------------- + + +.. py:class:: paddle.static.InputSpec(shape=None, dtype='float32', name=None) +用于描述模型输入的签名信息，包括shape、dtype和name。 + +此接口常用于指定高层API中模型的输入张量信息，或动态图转静态图时，指定被 ``paddle.jit.to_static`` 装饰的forward函数每个输入参数的张量信息。 + +参数： + - **shape** (list|tuple)- 声明维度信息的list或tuple，默认值为None。 + - **dtype** (np.dtype|VarType|str，可选)- 数据类型，支持bool，float16，float32，float64，int8，int16，int32，int64，uint8。默认值为float32。 + - **name** (str)- 被创建对象的名字，具体用法请参见 :ref:`api_guide_Name` 。 + +返回：初始化后的 ``InputSpec`` 对象 + +返回类型：InputSpec + +**代码示例** + +.. code-block:: python + + from paddle.static import InputSpec + + input = InputSpec([None, 784], 'float32', 'x') + label = InputSpec([None, 1], 'int64', 'label') + print(input) # InputSpec(shape=(-1, 784), dtype=VarType.FP32, name=x) + print(label) # InputSpec(shape=(-1, 1), dtype=VarType.INT64, name=label) + + +.. py:method:: from_tensor(tensor, name=None) +该接口将根据输入Tensor的shape、dtype等信息构建InputSpec对象。 + +参数： + - **tensor** (Tensor) - 用于构建InputSpec的源Tensor + - **name** (str): 被创建对象的名字，具体用法请参见 :ref:`api_guide_Name` 。 默认为：None。 + + +返回：根据Tensor信息构造的 ``InputSpec`` 对象 + +返回类型：InputSpec + + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + from paddle.static import InputSpec + + paddle.disable_static() + + x = paddle.to_tensor(np.ones([2, 2], np.float32)) + x_spec = InputSpec.from_tensor(x, name='x') + print(x_spec) # InputSpec(shape=(2, 2), dtype=VarType.FP32, name=x) + + +.. py:method:: from_numpy(ndarray, name=None) +该接口将根据输入numpy ndarray的shape、dtype等信息构建InputSpec对象。 + +参数： + - **ndarray** (Tensor) - 用于构建InputSpec的numpy ndarray + - **name** (str): 被创建对象的名字，具体用法请参见 :ref:`api_guide_Name` 。 默认为：None。 + + +返回：根据ndarray信息构造的 ``InputSpec`` 对象 + +返回类型：InputSpec + + +**代码示例** + +.. code-block:: python + + import numpy as np + from paddle.static import InputSpec + + x = np.ones([2, 2], np.float32) + x_spec = InputSpec.from_numpy(x, name='x') + print(x_spec) # InputSpec(shape=(2, 2), dtype=VarType.FP32, name=x) + + +.. py:method:: batch(batch_size) +该接口将batch_size插入到当前InputSpec对象的shape元组最前面。 + +参数： + - **batch_size** (int) - 被插入的batch size整型数值 + +返回： 更新shape信息后的 ``InputSpec`` 对象 + +返回类型：InputSpec + + +**代码示例** + +.. code-block:: python + + from paddle.static import InputSpec + + x_spec = InputSpec(shape=[64], dtype='float32', name='x') + x_spec.batch(4) + print(x_spec) # InputSpec(shape=(4, 64), dtype=VarType.FP32, name=x) + + +.. py:method:: unbatch() +该接口将当前InputSpec对象shape[0]值移除。 + + +返回： 更新shape信息后的 ``InputSpec`` 对象 + +返回类型：InputSpec + + +**代码示例** + +.. code-block:: python + + from paddle.static import InputSpec + + x_spec = InputSpec(shape=[4, 64], dtype='float32', name='x') + x_spec.unbatch() + print(x_spec) # InputSpec(shape=(64,), dtype=VarType.FP32, name=x) + diff --git a/doc/paddle/api/paddle/static/input/data_cn.rst b/doc/paddle/api/paddle/static/input/data_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..860068cbaf6259ccac54f619fdfbf3b48e3d3c87 --- /dev/null +++ b/doc/paddle/api/paddle/static/input/data_cn.rst @@ -0,0 +1,54 @@ +.. _cn_api_static_cn_data: + +data +------------------------------- + + +.. py:function:: paddle.static.data(name, shape, dtype=None, lod_level=0) + + + + +该OP会在全局block中创建变量（Variable），该全局变量可被计算图中的算子（operator）访问。该变量可作为占位符用于数据输入。例如用执行器（Executor）feed数据进该变量,当 ``dtype`` 为None时， ``dtype`` 将通过 ``padle.get_default_dtype()`` 获取全局类型。 + + +参数： + - **name** (str)- 被创建的变量的名字，具体用法请参见 :ref:`api_guide_Name` 。 + - **shape** (list|tuple)- 声明维度信息的list或tuple。可以在某个维度上设置None或-1，以指示该维度可以是任何大小。例如，将可变batchsize设置为None或-1。 + - **dtype** (np.dtype|str，可选)- 数据类型，支持bool，float16，float32，float64，int8，int16，int32，int64，uint8。默认值为None。当 ``dtype`` 为None时， ``dtype`` 将通过 ``padle.get_default_dtype()`` 获取全局类型。 + - **lod_level** (int，可选)- LoDTensor变量的LoD level数，LoD level是PaddlePaddle的高级特性，一般任务中不会需要更改此默认值，关于LoD level的详细适用场景和用法请见 :ref:`cn_user_guide_lod_tensor` 。默认值为0。 + +返回：全局变量，可进行数据访问 + +返回类型：Variable + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle.fluid as fluid + import paddle + # Creates a variable with fixed size [3, 2, 1] + # User can only feed data of the same shape to x + # the dtype is not set, so it will set "float32" by + # paddle.get_default_dtype(). You can use paddle.get_default_dtype() to + # change the global dtype + x = paddle.static.data(name='x', shape=[3, 2, 1]) + # Creates a variable with changeable batch size -1. + # Users can feed data of any batch size into y, + # but size of each data sample has to be [2, 1] + y = paddle.static.data(name='y', shape=[-1, 2, 1], dtype='float32') + z = x + y + # In this example, we will feed x and y with np-ndarray "1" + # and fetch z, like implementing "1 + 1 = 2" in PaddlePaddle + feed_data = np.ones(shape=[3, 2, 1], dtype=np.float32) + exe = fluid.Executor(fluid.CPUPlace()) + out = exe.run(fluid.default_main_program(), + feed={ + 'x': feed_data, + 'y': feed_data + }, + fetch_list=[z.name]) + # np-ndarray of shape=[3, 2, 1], dtype=float32, whose elements are 2 + print(out) diff --git a/doc/paddle/api/paddle/tensor/creation/diag_cn.rst b/doc/paddle/api/paddle/tensor/creation/diag_cn.rst index f08ae61e0e44c620ee20cadc979c91450aec9010..f525efb5890531e85eee24367e96b3f62c8fb0ea 100644 --- a/doc/paddle/api/paddle/tensor/creation/diag_cn.rst +++ b/doc/paddle/api/paddle/tensor/creation/diag_cn.rst @@ -1,38 +1,83 @@ -.. _cn_api_fluid_layers_diag: +.. _cn_api_paddle_cn_diag: diag ------------------------------- -.. py:function:: paddle.fluid.layers.diag(diagonal) +.. py:function:: paddle.diag(x, offset=0, padding_value=0, name=None) -:alias_main: paddle.diag -:alias: paddle.diag,paddle.tensor.diag,paddle.tensor.creation.diag -:old_api: paddle.fluid.layers.diag +如果 ``x`` 是向量（1-D张量），则返回带有 ``x`` 元素作为对角线的2-D方阵。 +如果 ``x`` 是矩阵（2-D张量），则提取 ``x`` 的对角线元素，以1-D张量返回。 -该OP创建一个方阵，使用输入diagonal来指定方阵的对角线元素的值。 +参数 ``offset`` 控制对角线偏移量： -参数： - - **diagonal** (Variable|numpy.ndarray) — 数据shape为 :math:`[N]` 一维Tensor，会把该Tensor的元素赋在方阵的对角线上。数据类型可以是 float32，float64，int32，int64。 +- 如果 ``offset`` = 0，则为主对角线。 +- 如果 ``offset`` > 0，则为上对角线。 +- 如果 ``offset`` < 0，则为下对角线。 -返回：存储着方阵的Tensor，对角线值是输入Tensor diagonal的值， 数据shape为 :math:`[N, N]` 二维Tensor。 +参数 +::::::::: + - x（Tensor）：输入的 `Tensor`。它的形状可以是一维或二维。其数据类型应为float32，float64，int32，int64。 + - offset（int，可选）：对角线偏移量。正值表示上对角线，0表示主对角线，负值表示下对角线。 + - padding_value（int|float，可选）：使用此值来填充指定对角线以外的区域。仅在输入为一维张量时生效。默认值为0。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回类型：Variable，数据类型和输入数据类型一致。 +返回 +::::::::: +``Tensor``，方阵或向量。输出数据类型与输入数据类型相同。 -**代码示例**： + +代码示例 1 +::::::::: + +.. code-block:: python + + import paddle + + paddle.disable_static() + x = paddle.to_tensor([1, 2, 3]) + y = paddle.diag(x) + print(y.numpy()) + # [[1 0 0] + # [0 2 0] + # [0 0 3]] + + y = paddle.diag(x, offset=1) + print(y.numpy()) + # [[0 1 0 0] + # [0 0 2 0] + # [0 0 0 3] + # [0 0 0 0]] + + y = paddle.diag(x, padding_value=6) + print(y.numpy()) + # [[1 6 6] + # [6 2 6] + # [6 6 3]] + + +代码示例 2 +::::::::: .. code-block:: python - # [3, 0, 0] - # [0, 4, 0] - # [0, 0, 5] + import paddle + + paddle.disable_static() + x = paddle.to_tensor([[1, 2, 3], [4, 5, 6]]) + y = paddle.diag(x) + print(y.numpy()) + # [1 5] + + y = paddle.diag(x, offset=1) + print(y.numpy()) + # [2 6] + + y = paddle.diag(x, offset=-1) + print(y.numpy()) + # [4] - import paddle.fluid as fluid - import numpy as np - diagonal = np.arange(3, 6, dtype='int32') - data = fluid.layers.diag(diagonal) - # diagonal.shape=(3,) data.shape=(3, 3) diff --git a/doc/paddle/api/paddle/tensor/creation/full_cn.rst b/doc/paddle/api/paddle/tensor/creation/full_cn.rst index 68dc4d658d9fe4b33ac852f1a8c91191a56363bf..c1d47170014bed30360eae294d3a8ebc8767452c 100644 --- a/doc/paddle/api/paddle/tensor/creation/full_cn.rst +++ b/doc/paddle/api/paddle/tensor/creation/full_cn.rst @@ -7,34 +7,30 @@ full -该OP创建形状大小为shape并且数据类型为dtype的Tensor，其中元素值均为 ``fill_value``。 +该OP创建形状大小为 ``shape`` 并且数据类型为 ``dtype`` 的Tensor，其中元素值均为 ``fill_value`` 。 参数： - **shape** (list|tuple|Tensor) – 指定创建Tensor的形状(shape), 数据类型为int32 或者int64。 - **fill_value** (bool|float|int|Tensor) - 用于初始化输出Tensor的常量数据的值。注意：该参数不可超过输出变量数据类型的表示范围。 - - **dtype** （np.dtype|core.VarDesc.VarType|str， 可选）- 输出变量的数据类型。若为None，则输出变量的数据类型和输入变量相同，默认值为None。 + - **dtype** （np.dtype|str， 可选）- 输出变量的数据类型。若为None，则输出变量的数据类型和输入变量相同，默认值为None。 - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回：返回一个存储结果的Tensor，数据类型和dtype相同。 -抛出异常： - - ``TypeError``: - 如果 ``dtype`` 的类型不是bool, float16, float32, float64, int32, int64其中之一。 - - ``TypeError``: - 如果 ``shape`` 的类型不是list或tuple或Tensor。当 ``shape`` 是Tensor的时候，其数据类型不是int32或者int64时。 - **代码示例**： .. code-block:: python import paddle - paddle.enable_imperative() # Now we are in imperative mode + paddle.disable_static() # Now we are in imperative mode data1 = paddle.full(shape=[2,1], fill_value=0, dtype='int64') #[[0] # [0]] # attr shape is a list which contains Tensor. - positive_3 = paddle.fill_constant([1], "int32", 2) + positive_2 = paddle.fill_constant([1], "int32", 2) data3 = paddle.full(shape=[1, positive_2], dtype='float32', fill_value=1.5) # [[1.5 1.5]] @@ -46,6 +42,6 @@ full # attr fill_value is a Tensor. val = paddle.fill_constant([1], "float32", 2.0) - data5 = paddle.full(shape=[2,1], fill_value=val, dtype='float32') i + data5 = paddle.full(shape=[2,1], fill_value=val, dtype='float32') # [[2.0] # [2.0]] diff --git a/doc/paddle/api/paddle/tensor/creation/full_like_cn.rst b/doc/paddle/api/paddle/tensor/creation/full_like_cn.rst index f0f26348adf85937abf5ad43d992918a557b2826..48b2a38cd67faa56b87942ac7aeea70d360eb25a 100644 --- a/doc/paddle/api/paddle/tensor/creation/full_like_cn.rst +++ b/doc/paddle/api/paddle/tensor/creation/full_like_cn.rst @@ -11,14 +11,11 @@ full_like 参数： - **x** (Tensor) – 输入Tensor, 输出Tensor和x具有相同的形状，x的数据类型可以是bool，float16，float32，float64，int32，int64。 - **fill_value** (bool|float|int) - 用于初始化输出张量的常量数据的值。注意：该参数不可超过输出变量数据类型的表示范围。 - - **dtype** （np.dtype|core.VarDesc.VarType|str， 可选）- 输出变量的数据类型。若参数为None，则输出变量的数据类型和输入变量相同，默认值为None。 + - **dtype** （np.dtype|str， 可选）- 输出变量的数据类型。若参数为None，则输出变量的数据类型和输入变量相同，默认值为None。 - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回：返回一个存储结果的Tensor，数据类型和dtype相同。 -抛出异常： - - ``TypeError``: - 当 ``x`` 的数据类型不是bool、float16、float32、float64、int32、int64其中之一。 - - ``TypeError``: - 当 ``dtype`` 不是bool、float16、float32、float64、int32、int64或者None其中之一。 **代码示例**： @@ -27,7 +24,7 @@ full_like import paddle import numpy as np - paddle.enable_imperative() # Now we are in imperative mode + paddle.disable_static() # Now we are in imperative mode input = paddle.full(shape=[2, 3], fill_value=0.0, dtype='float32', name='input') output = paddle.full_like(input, 2.0) # [[2. 2. 2.] diff --git a/doc/paddle/api/paddle/tensor/linalg/dot_cn.rst b/doc/paddle/api/paddle/tensor/linalg/dot_cn.rst index 70cadfbe67736bcbe560de0556d1f1d11425d9fa..242ea893d7b1ac3337e42d764aba4becdb9122d6 100644 --- a/doc/paddle/api/paddle/tensor/linalg/dot_cn.rst +++ b/doc/paddle/api/paddle/tensor/linalg/dot_cn.rst @@ -5,26 +5,22 @@ dot .. py:function:: paddle.tensor.linalg.dot(x, y, name=None) -:alias_main: paddle.dot -:alias: paddle.dot, paddle.tensor.dot, paddle.tensor.linalg.dot - - 该OP计算向量的内积 .. note:: - 仅支持1维Tensor(向量). + 支持1维和2维Tensor. 参数： - - **x** （Variable）- 1维 ``Tensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 - - **y** （Variable）- 1维 ``Tensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 + - **x** （Tensor）- 1维或2维 ``Tensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 + - **y** （Tensor）- 1维或2维 ``Tensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 - **name** （str，可选）- 输出的名字。默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。 返回： ``Tensor`` ，数据类型与 ``x`` 相同。 -返回类型： Variable。 +返回类型： Tensor。 **代码示例** @@ -32,11 +28,10 @@ dot import paddle import numpy as np - - paddle.enable_imperative() + paddle.disable_static() x_data = np.random.uniform(0.1, 1, [10]).astype(np.float32) y_data = np.random.uniform(1, 3, [10]).astype(np.float32) - x = paddle.imperative.to_variable(x_data) - y = paddle.imperative.to_variable(y_data) + x = paddle.to_variable(x_data) + y = paddle.to_variable(y_data) z = paddle.dot(x, y) print(z.numpy()) diff --git a/doc/paddle/api/paddle/tensor/linalg/norm_cn.rst b/doc/paddle/api/paddle/tensor/linalg/norm_cn.rst index 5fed454842b9292b2240cd8d3b575143064b0597..ea6ebd82d2aff71ea5164ce22063a5bf5723cdd7 100644 --- a/doc/paddle/api/paddle/tensor/linalg/norm_cn.rst +++ b/doc/paddle/api/paddle/tensor/linalg/norm_cn.rst @@ -7,7 +7,6 @@ norm :alias_main: paddle.norm :alias: paddle.norm,paddle.tensor.norm,paddle.tensor.linalg.norm -:update_api: paddle.fluid.layers.l2_normalize diff --git a/doc/paddle/api/paddle/tensor/logic/allclose_cn.rst b/doc/paddle/api/paddle/tensor/logic/allclose_cn.rst index e580aa233a340115835a263bf893422f055dc6b7..c483e3a112f2513f8db0bb7095dc1f99e7a4abd3 100644 --- a/doc/paddle/api/paddle/tensor/logic/allclose_cn.rst +++ b/doc/paddle/api/paddle/tensor/logic/allclose_cn.rst @@ -3,23 +3,18 @@ allclose ------------------------------- -.. py:function:: paddle.allclose(input, other, rtol=1e-05, atol=1e-08, equal_nan=False, name=None) +.. py:function:: paddle.allclose(x, y, rtol=1e-05, atol=1e-08, equal_nan=False, name=None) -:alias_main: paddle.allclose -:alias: paddle.allclose,paddle.tensor.allclose,paddle.tensor.logic.allclose - - - -逐个检查input和other的所有元素是否均满足如下条件： +逐个检查x和y的所有元素是否均满足如下条件： .. math:: - \left| input - other \right| \leq atol + rtol \times \left| other \right| + \left| x - y \right| \leq atol + rtol \times \left| y \right| 该API的行为类似于 :math:`numpy.allclose` ，即当两个待比较Tensor的所有元素均在一定容忍误差范围内视为相等则该API返回True值。 参数: - - **input** (Variable) - 第一个输入待比较Tensor input。 - - **other** (Variable) - 第二个输入待比较Tensor other。 + - **x** (Tensor) - 输入的 `Tensor` ，数据类型为：float32、float64。 + - **y** (Tensor) - 输入的 `Tensor` ，数据类型为：float32、float64。 - **rtol** (float，可选) - 相对容忍误差，默认值为1e-5。 - **atol** (float，可选) - 绝对容忍误差，默认值为1e-8。 - **equal_nan** (bool，可选) - 如果设置为True，则两个NaN数值将被视为相等，默认值为False。 @@ -27,43 +22,37 @@ allclose 返回：计算得到的布尔类型单值Tensor。 -返回类型：变量（Variable） - **代码示例**: .. code-block:: python import paddle - import paddle.fluid as fluid import numpy as np - use_cuda = fluid.core.is_compiled_with_cuda() - a = fluid.data(name="a", shape=[2], dtype='float32') - b = fluid.data(name="b", shape=[2], dtype='float32') - result = paddle.allclose(a, b, rtol=1e-05, atol=1e-08, + + paddle.disable_static() + + np_x = np.array([10000., 1e-07]).astype("float32") + np_y = np.array([10000.1, 1e-08]).astype("float32") + x = paddle.to_tensor (np_x) + y = paddle.to_tensor (np_y) + result1 = paddle.allclose(x, y, rtol=1e-05, atol=1e-08, + equal_nan=False, name="ignore_nan") + np_result1 = result1.numpy() + # [False] + result2 = paddle.allclose(x, y, rtol=1e-05, atol=1e-08, + equal_nan=True, name="equal_nan") + np_result2 = result2.numpy() + # [False] + + np_x = np.array([1.0, float('nan')]).astype("float32") + np_y = np.array([1.0, float('nan')]).astype("float32") + x = paddle.to_tensor (np_x) + y = paddle.to_tensor (np_y) + result1 = paddle.allclose(x, y, rtol=1e-05, atol=1e-08, equal_nan=False, name="ignore_nan") - result_nan = paddle.allclose(a, b, rtol=1e-05, atol=1e-08, + np_result1 = result1.numpy() + # [False] + result2 = paddle.allclose(x, y, rtol=1e-05, atol=1e-08, equal_nan=True, name="equal_nan") - place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - x = np.array([10000., 1e-07]).astype("float32") - y = np.array([10000.1, 1e-08]).astype("float32") - result_v, result_nan_v = exe.run( - feed={'a': x, 'b': y}, - fetch_list=[result, result_nan]) - print(result_v, result_nan_v) - # Output: (array([False]), array([False])) - x = np.array([10000., 1e-08]).astype("float32") - y = np.array([10000.1, 1e-09]).astype("float32") - result_v, result_nan_v = exe.run( - feed={'a': x, 'b': y}, - fetch_list=[result, result_nan]) - print(result_v, result_nan_v) - # Output: (array([ True]), array([ True])) - x = np.array([1.0, float('nan')]).astype("float32") - y = np.array([1.0, float('nan')]).astype("float32") - result_v, result_nan_v = exe.run( - feed={'a': x, 'b': y}, - fetch_list=[result, result_nan]) - print(result_v, result_nan_v) - # Output: (array([False]), array([ True])) + np_result2 = result2.numpy() + # [True] diff --git a/doc/paddle/api/paddle/tensor/manipulation/concat_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/concat_cn.rst index b66f67025f4171fa452534d173b3b63d86795b05..548f46e7804dd538369b580f52e351c34e3df91c 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/concat_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/concat_cn.rst @@ -15,11 +15,6 @@ concat 返回：联结后的Tensor ，数据类型和 ``x`` 中的Tensor相同。 -抛出异常： - - ``TypeError``: - 当输入 ``x`` 的类型不是list或者tuple时。 - - ``TypeError``: - 当输入 ``x`` 的数据类型不是 bool，float16， float32， float64， int32， int64时。 - - ``TypeError``: - 当 ``axis`` 的类型不是int或者Tensor时。 当 ``axis`` 是Tensor的时候其数据类型不是int32或者int64时。 - - ``TypeError``: - 当输入 ``x`` 中的Tensor存在数据类型不一致时。 **代码示例**： diff --git a/doc/paddle/api/paddle/tensor/manipulation/expand_as_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/expand_as_cn.rst index 3781c7c9343c5dc73c05f778814b9ca8b4b4bb50..2f62f67233c8e52f87f77e703c3e4499cb8fc40c 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/expand_as_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/expand_as_cn.rst @@ -1,68 +1,38 @@ -.. _cn_api_fluid_layers_expand_as: +.. _cn_api_tensor_expand_as: expand_as ------------------------------- -.. py:function:: paddle.fluid.layers.expand_as(x, target_tensor, name=None) +.. py:function:: paddle.expand_as(x, y, name=None) -:alias_main: paddle.expand_as -:alias: paddle.expand_as,paddle.tensor.expand_as,paddle.tensor.manipulation.expand_as -:old_api: paddle.fluid.layers.expand_as +根据 ``y`` 的形状扩展 ``x`` ，扩展后， ``x`` 的形状和 ``y`` 的形状相同。 +``x`` 的维数和 ``y`` 的维数应小于等于6，并且 ``y`` 的维数应该大于等于 ``x`` 的维数。扩展的维度的维度值应该为1。 +参数 +::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：bool、float32、float64、int32或int64。 + - y (Tensor) - 给定输入 ``x`` 扩展后的形状。 + - name (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 -该OP会根据输入的variable ``target_tensor`` 对输入 ``x`` 的各维度进行广播。通过 ``target_tensor``的维度来为 ``x`` 的每个维度设置广播的次数，使得x 的维度与target_tensor的维度相同。 ``x`` 的秩应小于等于6。注意， ``target_tensor`` 的秩必须与 ``x`` 的秩相同。 -注意:``target_tensor`` 对应的每一维必须能整除输入x中对应的维度，否则会报错。比如，target_tensor的维度为[2,6,2],x为[2,3,1],则整除后为[1,2,2]，x广播后维度为[2,6,2]。如果target_tensor的维度为[2,5,2]，第二维5不能整除x的第二维3，则会报错。 +返回 +::::::::: +``Tensor`` ，数据类型与 ``x`` 相同。 -以下是一个示例： +代码示例 +::::::::: -:: +.. code-block:: python - 输入(x) 是一个形状为[2, 3, 1]的 3-D Tensor : + import paddle + import numpy as np + + paddle.disable_static() + np_data_x = np.array([1, 2, 3]).astype('int32') + np_data_y = np.array([[1, 2, 3], [4, 5, 6]]).astype('int32') + data_x = paddle.to_tensor(np_data_x) + data_y = paddle.to_tensor(np_data_y) + out = paddle.expand_as(data_x, data_y) + np_out = out.numpy() + # [[1, 2, 3], [1, 2, 3]] - [ - [[1], [2], [3]], - [[4], [5], [6]] - ] - - target_tensor的维度 : [2, 6, 2] - - 输出(out) 是一个形状为[2, 6, 2]的 3-D Tensor: - - [ - [[1, 1], [2, 2], [3, 3], [1, 1], [2, 2], [3, 3]], - [[4, 4], [5, 5], [6, 6], [4, 4], [5, 5], [6, 6]] - ] - - - -参数: - - **x** （Variable）- 维度最高为6的多维 ``Tensor`` 或 ``LoDTensor``，数据类型为 ``float32``，``float64``，``int32`` 或 ``bool``。 - - **target_tensor** （list|tuple|Variable）- 数据类型为 ``float32``，``float64``，``int32`` 或 ``bool`` 。可为Tensor或者LODTensor。 - - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值： ``None``。 - -返回：维度与输入 ``x`` 相同的 ``Tensor`` 或 ``LoDTensor``，数据类型与 ``x`` 相同。返回值的每个维度的大小等于``target_tensor`` 对应的维度的大小。 - -返回类型：``Variable`` 。 - -抛出异常： - - :code:`ValueError`：``target_tensor`` 对应的每一维必须能整除输入x中对应的维度，否则会报错。 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - import numpy as np - data = fluid.data(name="data", shape=[-1,10], dtype='float64') - target_tensor = fluid.data(name="target_tensor", shape=[-1,20], dtype='float64') - result = fluid.layers.expand_as(x=data, target_tensor=target_tensor) - use_cuda = False - place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace() - exe = fluid.Executor(place) - exe.run(fluid.default_startup_program()) - x = np.random.rand(3,10) - y = np.random.rand(3,20) - output= exe.run(feed={"data":x,"target_tensor":y},fetch_list=[result.name]) - print(output[0].shape) - #(3,20) \ No newline at end of file diff --git a/doc/paddle/api/paddle/tensor/manipulation/expand_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/expand_cn.rst index 6bd61b1587e60420df20942a8da8c6382a1eef59..94af4e93fe13c2d5ff220c50b6a18f37e0491851 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/expand_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/expand_cn.rst @@ -1,71 +1,36 @@ -.. _cn_api_fluid_layers_expand: +.. _cn_api_tensor_expand: expand ------------------------------- -.. py:function:: paddle.fluid.layers.expand(x, expand_times, name=None) - -:alias_main: paddle.expand -:alias: paddle.expand,paddle.tensor.expand,paddle.tensor.manipulation.expand -:old_api: paddle.fluid.layers.expand - - - -该OP会根据参数 ``expand_times`` 对输入 ``x`` 的各维度进行复制。通过参数 ``expand_times`` 来为 ``x`` 的每个维度设置复制次数。 ``x`` 的秩应小于等于6。注意， ``expand_times`` 的大小必须与 ``x`` 的秩相同。以下是一个用例： - -:: - - 输入(x) 是一个形状为[2, 3, 1]的 3-D Tensor : - - [ - [[1], [2], [3]], - [[4], [5], [6]] - ] - - 属性(expand_times): [1, 2, 2] - - 输出(out) 是一个形状为[2, 6, 2]的 3-D Tensor: - - [ - [[1, 1], [2, 2], [3, 3], [1, 1], [2, 2], [3, 3]], - [[4, 4], [5, 5], [6, 6], [4, 4], [5, 5], [6, 6]] - ] - -参数: - - **x** （Variable）- 维度最高为6的多维 ``Tensor`` 或 ``LoDTensor``，数据类型为 ``float32``，``float64``，``int32`` 或 ``bool``。 - - **expand_times** （list|tuple|Variable）- 数据类型是 ``int32`` 。如果 ``expand_times`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[1]的 ``Tensor`` 或 ``LoDTensor``。如果 ``expand_times`` 的类型是 ``Variable``，则是1-D ``Tensor`` 或 ``LoDTensor``。表示 ``x`` 每一个维度被复制的次数。 - - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值： ``None``。 - -返回：维度与输入 ``x`` 相同的 ``Tensor`` 或 ``LoDTensor``，数据类型与 ``x`` 相同。返回值的每个维度的大小等于 ``x`` 的相应维度的大小乘以 ``expand_times`` 给出的相应值。 - -返回类型：``Variable`` 。 - -抛出异常： - - :code:`TypeError`：``expand_times`` 的类型应该是 list、tuple 或 Variable。 - - :code:`ValueError`：``expand_times`` 中的元素不能是负值。 - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - # example 1: - data_1 = fluid.layers.fill_constant(shape=[2, 3, 1], dtype='int32', value=0) - expanded_1 = fluid.layers.expand(data_1, expand_times=[1, 2, 2]) - # the shape of expanded_1 is [2, 6, 2]. - - # example 2: - data_2 = fluid.layers.fill_constant(shape=[12, 14], dtype="int32", value=3) - expand_times = fluid.layers.fill_constant(shape=[2], dtype="int32", value=4) - expanded_2 = fluid.layers.expand(data_2, expand_times=expand_times) - # the shape of expanded_2 is [48, 56]. +.. py:function:: paddle.expand(x, shape, name=None) +根据 ``shape`` 指定的形状扩展 ``x`` ，扩展后， ``x`` 的形状和 ``shape`` 指定的形状一致。 +``x`` 的维数和 ``shape`` 的元素数应小于等于6，并且 ``shape`` 中的元素数应该大于等于 ``x`` 的维数。扩展的维度的维度值应该为1。 +参数 +::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：bool、float32、float64、int32或int64。 + - shape (tuple|list|Tensor) - 给定输入 ``x`` 扩展后的形状,若 ``shape`` 为list或者tuple，则其中的元素值应该为整数或者1-D Tensor，若 ``shape`` 类型为Tensor，则其应该为1-D Tensor。 + - name (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 +返回 +::::::::: +``Tensor`` ，数据类型与 ``x`` 相同。 +代码示例 +::::::::: +.. code-block:: python + import paddle + import numpy as np + + paddle.disable_static() + np_data = np.array([1, 2, 3]).astype('int32') + data = paddle.to_tensor(np_data) + out = paddle.expand(data, [2, 3]) + np_out = out.numpy() + # [[1, 2, 3], [1, 2, 3]] diff --git a/doc/paddle/api/paddle/tensor/manipulation/gather_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/gather_cn.rst index 79a40cd49b9c33f7247e8b7cad69d88991cc7eb4..7cda6107ba2e08103d49dc65a5059341a024a0fd 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/gather_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/gather_cn.rst @@ -29,10 +29,6 @@ gather **返回**：和输入的秩相同的输出Tensor。 -抛出异常： - - ``TypeError``: - ``x`` 必须是Tensor 并且 ``x`` 的数据类型必须是uint8、float16、float32、float64、int32或者int64。 - - ``TypeError``: - ``index`` 必须是Tensor并且数据类型必须是int32或者int64。 - - ``TypeError``: - ``axis`` 必须是Tensor或者int, 当 ``axis`` 是Tensor的时候数据类型必须是int32或者int64。 **代码示例**： diff --git a/doc/paddle/api/paddle/tensor/manipulation/reshape_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/reshape_cn.rst index a5e39dff07f19832e9468f7deea5cc43b366a33d..e2a892314e8361cc76f568014bc32cb0fbb8124c 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/reshape_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/reshape_cn.rst @@ -5,11 +5,6 @@ reshape .. py:function:: paddle.fluid.layers.reshape(x, shape, actual_shape=None, act=None, inplace=False, name=None) -:alias_main: paddle.reshape -:alias: paddle.reshape,paddle.tensor.reshape,paddle.tensor.manipulation.reshape -:old_api: paddle.fluid.layers.reshape - - 该OP在保持输入 ``x`` 数据不变的情况下，改变 ``x`` 的形状。 @@ -31,26 +26,21 @@ reshape 2. 给定一个形状为[2,4,6]的三维张量x，目标形状为[2,3,-1,2]，则将x变换为形状为[2,3,4,2]的4-D张量，且x的数据保持不变。在这种情况下，目标形状的一个维度被设置为-1，这个维度的值是从x的元素总数和剩余维度推断出来的。 3. 给定一个形状为[2,4,6]的三维张量x，目标形状为[-1,0,3,2]，则将x变换为形状为[2,4,3,2]的4-D张量，且x的数据保持不变。在这种情况下，0对应位置的维度值将从x的对应维数中复制,-1对应位置的维度值由x的元素总数和剩余维度推断出来。 -**注意：参数** ``actual_shape`` **之后将被舍弃，只用参数** ``shape`` **来表示目标形状。** +.. warning:: +参数 ``actual_shape`` 之后将被舍弃，只用参数 ``shape`` 来表示目标形状。 参数： - - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor``，数据类型为 ``float32``，``float64``，``int32``，或 ``int64``。 - - **shape** （list|tuple|Variable）- 数据类型是 ``int32`` 。定义目标形状。目标形状最多只能有一个维度为-1。如果 ``shape`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[1]的 ``Tensor`` 或 ``LoDTensor``。如果 ``shape`` 的类型是 ``Variable``，则是1-D的 ``Tensor`` 或 ``LoDTensor``。 - - **actual_shape** （Variable，可选）- 1-D ``Tensor`` 或 ``LoDTensor``，默认值：`None`。如果 ``actual_shape`` 被提供，``actual_shape`` 具有比 ``shape`` 更高的优先级，此时 ``shape`` 只能是整数列表或元组。更新提示：``actual_shape`` 在未来的版本中将被舍弃，并用 ``shape`` 代替。 + - **x** （Tensor）- N-D ``Tensor``，数据类型为 ``float32``，``float64``，``int32``，或 ``int64``。 + - **shape** （list|tuple|Tensor）- 数据类型是 ``int32`` 。定义目标形状。目标形状最多只能有一个维度为-1。如果 ``shape`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[1]的 ``Tensor``。如果 ``shape`` 的类型是 ``Tensor``，则是1-D的 ``Tensor``。 + - **actual_shape** （Tensor，可选）- 1-D ``Tensor``，默认值：`None`。如果 ``actual_shape`` 被提供，``actual_shape`` 具有比 ``shape`` 更高的优先级，此时 ``shape`` 只能是整数列表或元组。更新提示：``actual_shape`` 在未来的版本中将被舍弃，并用 ``shape`` 代替。 - **act** （str，可选）- 对形状改变后的输入变量做非线性激活操作，激活函数类型可以参考 :ref:`api_guide_activations` 。默认值： ``None``。 - **inplace** （bool，可选）- 如果 ``inplace`` 为 ``True``，则 ``layers.reshape`` 的输入和输出是同一个变量，否则 ``layers.reshape`` 的输入和输出是不同的变量。默认值：``False``。请注意，如果 ``x`` 是多个OP的输入，则 ``inplace`` 必须为False。 - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值： ``None``。 -返回：多维 ``Tensor`` 或 ``LoDTensor``，数据类型与 ``input`` 相同。如果 ``inplace`` 为 ``False``，则返回一个新的变量，否则将改变输入变量 ``x`` 自身。如果 ``act`` 为 ``None``，则直接返回形状改变后的变量，否则返回经过激活函数后的变量。 - -返回类型：Variable。 +返回： +::::::::: +``Tensor``，改变形状后的 ``Tensor``，数据类型与 ``x`` 相同。如果 ``inplace`` 为 ``False``，则返回一个新的变量，否则将改变输入变量 ``x`` 自身。如果 ``act`` 为 ``None``，则直接返回形状改变后的变量，否则返回经过激活函数后的变量。 -抛出异常： - - :code:`TypeError`：``actual_shape`` 的类型应该是 Variable 或 None。 - - :code:`TypeError`：``starts`` 的类型应该是list、tuple 或 Variable。 - - :code:`ValueError`：``shape`` 中至多有一个元素可以是-1。 - - :code:`ValueError`：``shape`` 中的元素为0时，对应的维度应该小于等于``x``的维度。 - - :code:`ValueError`：``shape`` 中的元素除了-1之外，都应该是非负值。 **代码示例** @@ -59,7 +49,7 @@ reshape import paddle.fluid as fluid # example 1: - # attr shape is a list which doesn't contain tensor Variable. + # attr shape is a list which doesn't contain Tensors. data_1 = fluid.data( name='data_1', shape=[2, 4, 6], dtype='float32') reshaped_1 = fluid.layers.reshape( @@ -67,7 +57,7 @@ reshape # the shape of reshaped_1 is [2,4,3,2]. # example 2: - # attr shape is a list which contains tensor Variable. + # attr shape is a list which contains Tensors. data_2 = fluid.layers.fill_constant([2,25], "int32", 3) dim = fluid.layers.fill_constant([1], "int32", 5) reshaped_2 = fluid.layers.reshape(data_2, shape=[dim, 10]) diff --git a/doc/paddle/api/paddle/tensor/manipulation/scatter_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/scatter_cn.rst index 38824d7fbdd7d3aa250f24e4b8185b3399f53b5b..43a9aad6d7d9f4d06a6cd3f544ed13af6428c1bd 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/scatter_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/scatter_cn.rst @@ -1,79 +1,78 @@ -.. _cn_api_fluid_layers_scatter: +.. _cn_api_paddle_cn_scatter: scatter ------------------------------- +.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None) + + +通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下： + + .. code-block:: python + + import numpy as np + #input: + x = np.array([[1, 1], [2, 2], [3, 3]]) + index = np.array([2, 1, 0, 1]) + # shape of updates should be the same as x + # shape of updates with dim > 1 should be the same as input + updates = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]) + overwrite = False + # calculation: + if not overwrite: + for i in range(len(index)): + x[index[i]] = np.zeros((2)) + for i in range(len(index)): + if (overwrite): + x[index[i]] = updates[i] + else: + x[index[i]] += updates[i] + # output: + out = np.array([[3, 3], [6, 6], [1, 1]]) + out.shape # [3, 2] + +**Notice：** +因为 ``updates`` 的应用顺序是不确定的，因此，如果索引 ``index`` 包含重复项，则输出将具有不确定性。 -.. py:function:: paddle.fluid.layers.scatter(input, index, updates, name=None, overwrite=True) - -:alias_main: paddle.scatter -:alias: paddle.scatter,paddle.tensor.scatter,paddle.tensor.manipulation.scatter -:old_api: paddle.fluid.layers.scatter - - - -该OP根据index中的索引值将updates数据更新到input中。 - -.. code-block:: python - - 输入： - input = np.array([[1, 1], [2, 2], [3, 3]]) - index = np.array([2, 1, 0, 1]) - # updates的维度需要和input一样 - # updates 维度 > 1 的shape要和input一样 - updates = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]) - overwrite = False - - 计算过程： - if not overwrite: - for i in range(len(index)): - input[index[i]] = np.zeros((2)) - - # 根据index中的索引值取updates中的数据更新到input中去 - for i in range(len(index)): - if (overwirte): - input[index[i]] = updates[i] - else: - input[index[i]] += updates[i] - - 输出： - out # np.array([[3, 3], [6, 6], [1, 1]]) - out.shape # [3, 2] 参数： - - **input** （Variable） - 支持任意纬度的Tensor。支持的数据类型为float32。 - - **index** （Variable） - 表示索引，仅支持1-D Tensor。 支持的数据类型为int32，int64。 - - **updates** （Variable） - 根据索引的值将updates Tensor中的对应值更新到input Tensor中，updates Tensor的维度需要和input tensor保持一致，且除了第一维外的其他的维度的大小需要和input Tensor保持相同。支持的数据类型为float32。 - - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - - **overwrite** （bool，可选） - 如果index中的索引值有重复且overwrite 为True，旧更新值将被新的更新值覆盖；如果为False，新的更新值将同旧的更新值相加。默认值为True。 - -返回：返回类型为Variable(Tensor|LoDTensor)，数据类型以及shape大小同输入一致。 - -**代码示例** - -.. code-block:: python - - import numpy as np - import paddle.fluid as fluid - - input = fluid.layers.data(name='data', shape=[3, 2], dtype='float32', append_batch_size=False) - index = fluid.layers.data(name='index', shape=[4], dtype='int64', append_batch_size=False) - updates = fluid.layers.data(name='update', shape=[4, 2], dtype='float32', append_batch_size=False) - - output = fluid.layers.scatter(input, index, updates, overwrite=False) - - exe = fluid.Executor(fluid.CPUPlace()) - exe.run(fluid.default_startup_program()) - - in_data = np.array([[1, 1], [2, 2], [3, 3]]).astype(np.float32) - index_data = np.array([2, 1, 0, 1]).astype(np.int64) - update_data = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]).astype(np.float32) - - res = exe.run(fluid.default_main_program(), feed={'data':in_data, "index":index_data, "update":update_data}, fetch_list=[output]) - print(res) - # [array([[3., 3.], - # [6., 6.], - # [1., 1.]], dtype=float32)] - - - - + - **x** (Tensor) - ndim> = 1的输入N-D张量。 数据类型可以是float32，float64。 + - **index** （Tensor）- 一维Tensor。 数据类型可以是int32，int64。 ``index`` 的长度不能超过 ``updates`` 的长度，并且 ``index`` 中的值不能超过输入的长度。 + - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x`` 。 形状应与输入 ``x`` 相同，并且dim>1的dim值应与输入 ``x`` 相同。 + - **overwrite** （bool，可选）- 指定索引 ``index`` 相同时，更新输出的方式。如果为True，则使用覆盖模式更新相同索引的输出，如果为False，则使用累加模式更新相同索引的输出。默认值为True。 + - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：Tensor，与x有相同形状和数据类型。 + + +**代码示例：** + .. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + x_data = np.array([[1, 1], [2, 2], [3, 3]]).astype(np.float32) + index_data = np.array([2, 1, 0, 1]).astype(np.int64) + updates_data = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]).astype(np.float32) + + x = paddle.to_tensor(x_data) + index = paddle.to_tensor(index_data) + updates = paddle.to_tensor(updates_data) + + output1 = paddle.scatter(x, index, updates, overwrite=False) + # [[3., 3.], + # [6., 6.], + # [1., 1.]] + output2 = paddle.scatter(x, index, updates, overwrite=True) + # CPU device: + # [[3., 3.], + # [4., 4.], + # [1., 1.]] + # GPU device maybe have two results because of the repeated numbers in index + # result 1: + # [[3., 3.], + # [4., 4.], + # [1., 1.]] + # result 2: + # [[3., 3.], + # [2., 2.], + # [1., 1.]] diff --git a/doc/paddle/api/paddle/tensor/manipulation/split_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/split_cn.rst index 9c1293baf3fb9793ff079a38d18459d24bef7cf8..d7421732749cd2cb0892d98371d2ca6d0da50540 100644 --- a/doc/paddle/api/paddle/tensor/manipulation/split_cn.rst +++ b/doc/paddle/api/paddle/tensor/manipulation/split_cn.rst @@ -16,10 +16,6 @@ split 返回：分割后的Tensor列表。 -抛出异常： - - :code:`TypeError`：``x`` 的数据类型不是bool、float16、float32、float64、int32或int64时 。 - - :code:`TypeError`：``num_or_sections`` 不是int、list 或 tuple时。 - - :code:`TypeError`：``axis`` 不是 int 或 Tensor时。当 ``axis`` 为Tensor，其数据类型不是int32或int64时。 **代码示例**： diff --git a/doc/paddle/api/paddle/tensor/manipulation/tile_cn.rst b/doc/paddle/api/paddle/tensor/manipulation/tile_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..3d8e989d4fbf50ce7e87148fd101adc417b567e5 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/manipulation/tile_cn.rst @@ -0,0 +1,45 @@ +.. _cn_api_tensor_tile: + +tile +------------------------------- + +.. py:function:: paddle.tile(x, repeat_times, name=None) + +根据参数 ``repeat_times`` 对输入 ``x`` 的各维度进行复制。 + +``x`` 的维数和 ``repeat_times`` 中的元素数量应小于等于6，并且repeat_times中的元素数量应该小于等于6。 + +参数 +::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：bool、float32、float64、int32或int64。 + - repeat_times (list|tuple|Tensor) - 指定输入 ``x`` 每个维度的复制次数。如果 ``repeat_times`` 的类型是list或tuple，它的元素可以是整数或者数据类型为int32的1-D Tensor。如果 ``repeat_times`` 的类型是Tensor，则是数据类型为int32的1-D Tensor。 + - name (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +``Tensor`` ，数据类型与 ``x`` 相同。返回值的第i维的大小等于 ``x[i] * repeat_times[i]`` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np_data = np.array([1, 2, 3]).astype('int32') + data = paddle.to_tensor(np_data) + out = paddle.tile(data, repeat_times=[2, 1]) + np_out = out.numpy() + # [[1, 2, 3], [1, 2, 3]] + + out = paddle.tile(data, repeat_times=[2, 2]) + np_out = out.numpy() + # [[1, 2, 3, 1, 2, 3], [1, 2, 3, 1, 2, 3]] + + np_repeat_times = np.array([2, 1]).astype("int32") + repeat_times = paddle.to_tensor(np_repeat_times) + out = paddle.tile(data, repeat_times=repeat_times) + np_out = out.numpy() + # [[1, 2, 3], [1, 2, 3]] diff --git a/doc/paddle/api/paddle/tensor/math/add_cn.rst b/doc/paddle/api/paddle/tensor/math/add_cn.rst index 5673e801092d6af999465df5073fa22efad24779..94162e5c8419121731a5dc89905c2e5bd9b1d898 100644 --- a/doc/paddle/api/paddle/tensor/math/add_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/add_cn.rst @@ -3,177 +3,47 @@ add ------------------------------- -.. py:function:: paddle.add(x, y, alpha=1, out=None, name=None) +.. py:function:: paddle.add(x, y, name=None) :alias_main: paddle.add :alias: paddle.add,paddle.tensor.add,paddle.tensor.math.add :update_api: paddle.fluid.layers.elementwise_add - 该OP是逐元素相加算子，输入 ``x`` 与输入 ``y`` 逐元素相加，并将各个位置的输出元素保存到返回结果中。 +输入 ``x`` 与输入 ``y`` 必须可以广播为相同形状, 关于广播规则，请参考 :ref:`use_guide_broadcasting` + 等式为： .. math:: Out = X + Y - :math:`X` ：多维Tensor。 -- :math:`Y` ：维度必须小于等于X维度的Tensor。 - -对于这个运算算子有2种情况： - 1. :math:`Y` 的 ``shape`` 与 :math:`X` 相同。 - 2. :math:`Y` 的 ``shape`` 是 :math:`X` 的连续子序列。 - -对于情况2: - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 是 :math:`Y` 在 :math:`X` 上的起始维度的位置。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾部维度将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: text - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 +- :math:`Y` ：多维Tensor。 参数： - - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64``。 - - **y** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64``。 - - **alpha** （int|float，可选）- 输入y的缩放因子。默认值为1. 如果alpha不为1，本api计算公式变为 :math:`Out = X + alpha * Y` - - **out** （Variable，可选）- 指定存储运算结果的 ``Tensor`` 。如果设置为None或者不设置，将创建新的 ``Tensor`` 存储运算结果，默认值为None。 - - **name** （str，可选）- 输出的名字。默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64、int32、int64。 + - y (Tensor) - 输入的Tensor，数据类型为：float32、float64、int32、int64。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 +返回： 多维Tensor, 数据类型与 ``x`` 相同, 维度为广播后的形状。 -返回： 多维 ``Tensor`` 或 ``LoDTensor`` ，维度和数据类型都与 ``x`` 相同。 +返回类型： Tensor -返回类型： Variable -**代码示例 1** +**代码示例** .. code-block:: python import paddle - import paddle.fluid as fluid import numpy as np - def gen_data(): - return { - "x": np.array([2, 3, 4]).astype('float32'), - "y": np.array([1, 5, 2]).astype('float32') - } - - x = fluid.data(name="x", shape=[3], dtype='float32') - y = fluid.data(name="y", shape=[3], dtype='float32') - z1 = paddle.add(x, y) - z2 = paddle.add(x, y, alpha=10) - # z = x + y - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - z_value = exe.run(feed=gen_data(), - fetch_list=[z1.name, z2.name]) - - print(z_value[0]) # [3., 8., 6.] - print(z_value[1]) # [12. 53. 24.] - -**代码示例 2** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - def gen_data(): - return { - "x": np.ones((2, 3, 4, 5)).astype('float32'), - "y": np.zeros((4, 5)).astype('float32') - } - - x = fluid.data(name="x", shape=[2, 3, 4, 5], dtype='float32') - y = fluid.data(name="y", shape=[4, 5], dtype='float32') - z = paddle.add(x, y, name='z') - # z = x + y - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - - z_value = exe.run(feed=gen_data(), - fetch_list=[z.name]) - - print(z_value[0]) - print(z_value[0].shape) # z.shape=[2,3,4,5] - -**代码示例 3** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - def gen_data(): - return { - "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'), - "y": np.random.randint(1, 5, size=[5]).astype('float32') - } - - x = fluid.data(name="x", shape=[2,3,4,5], dtype='float32') - y = fluid.data(name="y", shape=[5], dtype='float32') + paddle.enable_imperative() + np_x = np.array([2, 3, 4]).astype('float64') + np_y = np.array([1, 5, 2]).astype('float64') + x = paddle.imperative.to_variable(np_x) + y = paddle.imperative.to_variable(np_y) z = paddle.add(x, y) - # z = x / y - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - - z_value = exe.run(feed=gen_data(), - fetch_list=[z.name]) - print(z_value[0]) - print(z_value[0].shape) # z.shape=[2,3,4,5] - - -**代码示例 4** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - x = fluid.data(name="x", shape=[3], dtype="float32") - y = fluid.data(name='y', shape=[3], dtype='float32') - - output = fluid.data(name="output", shape=[3], dtype="float32") - z = paddle.add(x, y, out=output) - - place = fluid.CPUPlace() - exe = fluid.Executor(place) - data1 = np.array([2, 3, 4], dtype='float32') - data2 = np.array([1, 5, 2], dtype='float32') - z_value = exe.run(feed={'x': data1, - 'y': data2}, - fetch_list=[z]) - print(z_value[0]) # [3. 8. 6.] - - -**代码示例 5（动态图）** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np - - with fluid.dygraph.guard(): - np_x = np.array([2, 3, 4]).astype('float64') - np_y = np.array([1, 5, 2]).astype('float64') - x = fluid.dygraph.to_variable(np_x) - y = fluid.dygraph.to_variable(np_y) - z = paddle.add(x, y, alpha=-0.5) - np_z = z.numpy() - print(np_z) # [1.5, 0.5, 3. ] + np_z = z.numpy() + print(np_z) # [3., 8., 6. ] diff --git a/doc/paddle/api/paddle/tensor/math/clip_cn.rst b/doc/paddle/api/paddle/tensor/math/clip_cn.rst index 071fe323ffdf8de41a454669e3b23e2f7f976a4b..a84d2a57ccd7362d6211198756b3b4dc89bfdf5d 100644 --- a/doc/paddle/api/paddle/tensor/math/clip_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/clip_cn.rst @@ -1,41 +1,46 @@ -.. _cn_api_fluid_layers_clip: +.. _cn_api_tensor_clip: clip ------------------------------- -.. py:function:: paddle.fluid.layers.clip(x, min, max, name=None) +.. py:function:: paddle.clip(x, min=None, max=None, name=None) -:alias_main: paddle.nn.clip -:alias: paddle.nn.clip,paddle.nn.clip.clip -:old_api: paddle.fluid.layers.clip +:alias_main: paddle.clip +:alias: paddle.clip,paddle.tensor.clip,paddle.tensor.math.clip -该OP对输入Tensor每个元素的数值进行裁剪，使得输出Tensor元素的数值被限制在区间[min, max]内。具体的计算公式为如下。 +该OP将输入的所有元素进行剪裁，使得输出元素限制在[min, max]内，具体公式如下： .. math:: - Out = MIN(MAX(x,min),max) - - + Out = MIN(MAX(x, min), max) 参数： - - **x** (Variable)- 多维Tensor，数据类型为float32 - - **min** (float)- 最小值，输入Tensor中小于该值的元素由min代替。 - - **max** (float)- 最大值，输入Tensor中大于该值的元素由max替换。 - - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。 + - min (float32|Tensor, 可选) - 裁剪的最小值，输入中小于该值的元素将由该元素代替，若参数为空，则不对输入的最小值做限制。数据类型可以是float32或形状为[1]的Tensor，类型可以为int32，float32，float64，默认值为None。 + - max (float32|Tensor, 可选) - 裁剪的最大值，输入中大于该值的元素将由该元素代替，若参数为空，则不对输入的最大值做限制。数据类型可以是float32或形状为[1]的Tensor，类型可以为int32，float32，float64，默认值为None。 + - name (str，可选） - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回： 对元素的数值进行裁剪之后的Tesnor，与输入x具有相同的shape和数据类型 +返回：输出Tensor，与 ``x`` 维度相同、数据类型相同。 -返回类型：Variable +返回类型：Tensor -**代码示例：** +**代码示例**： .. code-block:: python - import paddle.fluid as fluid - input = fluid.layers.data( - name='data', shape=[1], dtype='float32') - reward = fluid.layers.clip(x=input, min=-1.0, max=1.0) - - + import paddle + import numpy as np + + paddle.disable_static() + x = np.array([[1.2,3.5], [4.5,6.4]]).astype('float32') + x1 = paddle.to_tensor(x) + out1 = paddle.clip(x1, min=3.5, max=5.0) + out2 = paddle.clip(x1, min=2.5) + print(out1.numpy()) + # [[3.5, 3.5] + # [4.5, 5.0]] + print(out2.numpy()) + # [[2.5, 3.5] + # [[4.5, 6.4] diff --git a/doc/paddle/api/paddle/tensor/math/divide_cn.rst b/doc/paddle/api/paddle/tensor/math/divide_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d0b0113c24644f5e5e55b4a3a73722da63610df4 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/divide_cn.rst @@ -0,0 +1,43 @@ +.. _cn_api_tensor_divide: + +divide +------------------------------- + +.. py:function:: paddle.divide(x, y, name=None) + +该OP是逐元素相除算子，输入 ``x`` 与输入 ``y`` 逐元素相除，并将各个位置的输出元素保存到返回结果中。 +输入 ``x`` 与输入 ``y`` 必须可以广播为相同形状, 关于广播规则，请参考 :ref:`use_guide_broadcasting` + +等式为： + +.. math:: + Out = X / Y + +- :math:`X` ：多维Tensor。 +- :math:`Y` ：多维Tensor。 + +参数： + - x（Tensor）- 多维Tensor。数据类型为float32 、float64、int32或int64。 + - y（Tensor）- 多维Tensor。数据类型为float32 、float64、int32或int64。 + - name（str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +返回： 多维 Tensor， 数据类型与 ``x`` 相同，维度为广播后的形状。 + +返回类型： Tensor + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np_x = np.array([2, 3, 4]).astype('float64') + np_y = np.array([1, 5, 2]).astype('float64') + x = paddle.to_tensor(np_x) + y = paddle.to_tensor(np_y) + z = paddle.divide(x, y) + print(z.numpy()) # [2., 0.6, 2.] diff --git a/doc/paddle/api/paddle/tensor/math/floor_divide_cn.rst b/doc/paddle/api/paddle/tensor/math/floor_divide_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..c63ae4fd10451f280169d67c8156fa30f92649d7 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/floor_divide_cn.rst @@ -0,0 +1,43 @@ +.. _cn_api_tensor_floor_divide: + +floor_divide +------------------------------- + +.. py:function:: paddle.floor_divide(x, y, name=None) + +该OP是逐元素整除算子，输入 ``x`` 与输入 ``y`` 逐元素整除，并将各个位置的输出元素保存到返回结果中。 +输入 ``x`` 与输入 ``y`` 必须可以广播为相同形状, 关于广播规则，请参考 :ref:`use_guide_broadcasting` + +等式为： + +.. math:: + Out = X // Y + +- :math:`X` ：多维Tensor。 +- :math:`Y` ：多维Tensor。 + +参数： + - x（Tensor）- 多维Tensor。数据类型为int32或int64。 + - y（Tensor）- 多维Tensor。数据类型为int32或int64。 + - name（str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +返回： 多维 Tensor， 数据类型与 ``x`` 相同，维度为广播后的形状。 + +返回类型： Tensor + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np_x = np.array([2, 3, 8, 7]) + np_y = np.array([1, 5, 3, 3]) + x = paddle.to_tensor(np_x) + y = paddle.to_tensor(np_y) + z = paddle.floor_divide(x, y) + print(z.numpy()) # [2, 0, 2, 2] \ No newline at end of file diff --git a/doc/paddle/api/paddle/tensor/math/floor_mod_cn.rst b/doc/paddle/api/paddle/tensor/math/floor_mod_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..e9b9773c09dfef8d15f85f62edd4ebcb09c86b4b --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/floor_mod_cn.rst @@ -0,0 +1,7 @@ +.. _cn_api_tensor_cn_floor_mod: + +floor_mod +------------------------------- +:doc_source: paddle.tensor.remainder + + diff --git a/doc/paddle/api/paddle/tensor/math/isfinite_cn.rst b/doc/paddle/api/paddle/tensor/math/isfinite_cn.rst index c9b5474e809b248141ad4632e5a5aedd1e11fec9..0cc20e3e2335cc100d6275c6936d7bc347b17454 100644 --- a/doc/paddle/api/paddle/tensor/math/isfinite_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/isfinite_cn.rst @@ -1,49 +1,30 @@ -.. _cn_api_fluid_layers_isfinite: +.. _cn_api_tensor_isfinite: isfinite -------------------------------- +----------------------------- -.. py:function:: paddle.fluid.layers.isfinite(x) +.. py:function:: paddle.tensor.isfinite(x, name=None) -:alias_main: paddle.isfinite -:alias: paddle.isfinite,paddle.tensor.isfinite,paddle.tensor.logic.isfinite -:old_api: paddle.fluid.layers.isfinite +返回输入tensor的每一个值是否为 `Finite` （既非 `+/-INF` 也非 `+/-NaN` ）。 +参数 +::::::::: + - **x** (Tensor): 输入的 `Tensor` ，数据类型为：float16、float32、float64、int32、int64。 + - **name** (str, 可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 +返回 +::::::::: +``Tensor``, 每个元素是一个bool值，表示输入 `x` 的每个元素是否为 `Finite` （既非 `+/-INF` 也非 `+/-NaN` ）。 -``注意：此算子的输入 Tensor / LoDTensor 数据类型必须为 int32 / float / double 之一。`` - -测试 x 是否包含无穷值（即 nan 或 inf）。若元素均为有穷数，返回真；否则返回假。 - -参数： - - **x(variable)** : 变量，包含被测试的 Tensor / LoDTensor。 - -返回: - - Variable (Tensor / LoDTensor)，此 Tensor 变量包含一个 bool 型结果。 - -返回类型 - - Variable (Tensor / LoDTensor)，一个包含 Tensor 的变量。 - -**代码示例**： +代码示例 +::::::::: .. code-block:: python - import paddle.fluid as fluid - import numpy - - # Graph Organizing - var = fluid.layers.data(name="data", shape=(4, 6), dtype="float32") - output = fluid.layers.isfinite(var) - - # Create an executor using CPU as an example - exe = fluid.Executor(fluid.CPUPlace()) - exe.run(fluid.default_startup_program()) - - # Execute - img = numpy.array((4, 6)).astype(numpy.float32) - res, = exe.run(fluid.default_main_program(), feed={'data':img}, fetch_list=[output]) - print(res) # Output Value: [ True] - - - - + import paddle + import numpy as np + paddle.disable_static() + x_np = np.array([float('-inf'), -2, 3.6, float('inf'), 0, float('-nan'), float('nan')]) + x = paddle.to_tensor(x_np) + out = paddle.tensor.isfinite(x) + print(out.numpy()) # [False True True False True False False] diff --git a/doc/paddle/api/paddle/tensor/math/isinf_cn.rst b/doc/paddle/api/paddle/tensor/math/isinf_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..1fdd20485f6c504d5dfcbd18198a5475eac79872 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/isinf_cn.rst @@ -0,0 +1,30 @@ +.. _cn_api_tensor_isinf: + +isinf +----------------------------- + +.. py:function:: paddle.tensor.isinf(x, name=None) + +返回输入tensor的每一个值是否为 `+/-INF` 。 + +参数 +::::::::: + - **x** (Tensor): 输入的 `Tensor` ，数据类型为：float16、float32、float64、int32、int64。 + - **name** (str, 可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +``Tensor``, 每个元素是一个bool值，表示输入 `x` 的每个元素是否为 `+/-INF` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + x_np = np.array([float('-inf'), -2, 3.6, float('inf'), 0, float('-nan'), float('nan')]) + x = paddle.to_tensor(x_np) + out = paddle.tensor.isinf(x) + print(out.numpy()) # [ True False False True False False False] diff --git a/doc/paddle/api/paddle/tensor/math/isnan_cn.rst b/doc/paddle/api/paddle/tensor/math/isnan_cn.rst index 2f22289cc74472058687a5ace267fc7ff66ebe00..5765ebf184254b87a72c9b5eb8a142d6cef879b1 100644 --- a/doc/paddle/api/paddle/tensor/math/isnan_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/isnan_cn.rst @@ -1,3 +1,30 @@ +.. _cn_api_tensor_isnan: + isnan -------------------------------- -**版本升级，文档正在开发中** +----------------------------- + +.. py:function:: paddle.tensor.isnan(x, name=None) + +返回输入tensor的每一个值是否为 `+/-NaN` 。 + +参数 +::::::::: + - **x** (Tensor): 输入的 `Tensor` ，数据类型为：float16、float32、float64、int32、int64。 + - **name** (str, 可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回 +::::::::: +``Tensor``, 每个元素是一个bool值，表示输入 `x` 的每个元素是否为 `+/-NaN` 。 + +代码示例 +::::::::: + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + x_np = np.array([float('-inf'), -2, 3.6, float('inf'), 0, float('-nan'), float('nan')]) + x = paddle.to_tensor(x_np) + out = paddle.tensor.isnan(x) + print(out.numpy()) # [False False False False False True True] diff --git a/doc/paddle/api/paddle/tensor/math/log1p_cn.rst b/doc/paddle/api/paddle/tensor/math/log1p_cn.rst index dab3f158a2d20ee31db2d492f647140ec80eea6f..ff96c608014e706910dbfc30fd11df02995717a8 100644 --- a/doc/paddle/api/paddle/tensor/math/log1p_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/log1p_cn.rst @@ -3,7 +3,7 @@ log1p ------------------------------- -.. py:function:: paddle.tensor.log1p(x, out=None, name=None) +.. py:function:: paddle.log1p(x, name=None) :alias_main: paddle.log1p :alias: paddle.log1p,paddle.tensor.log1p,paddle.tensor.math.log1p @@ -18,32 +18,27 @@ log1p 参数: - - **x** (Variable) – 该OP的输入为LodTensor/Tensor。数据类型为float32，float64。 - - **out** (Variable， 可选) - 指定算子输出结果的LoDTensor/Tensor，可以是程序中已经创建的任何Variable。默认值为None，此时将创建新的Variable来保存输出结果。 + - **x** (Tensor) – 指定输入为一个多维的Tensor。数据类型为float32，float64。 - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。 返回：Log1p算子自然对数输出 -返回类型: Variable - 该OP的输出为LodTensor/Tensor，数据类型为输入一致。 +返回类型: Tensor - 该OP的输出为一个多维的Tensor，数据类型为输入一致。 **代码示例** .. code-block:: python - import paddle - import paddle.fluid as fluid - import numpy as np - - x = fluid.data(name="x", shape=[2,1], dtype="float32") - res = paddle.log1p(x) # paddle.log1p等价于 paddle.tensor.log1p - - # 举例选择CPU计算环境 - exe = fluid.Executor(fluid.CPUPlace()) - - # 执行静态图，输出结果 - x_i = np.array([[0], [1]]).astype(np.float32) - res_val, = exe.run(fluid.default_main_program(), feed={'x':x_i}, fetch_list=[res]) - print(res_val) # [[0.], [0.6931472]] - - + import paddle + import numpy as np + + paddle.enable_imperative() + x = np.array([[1, 2], [3, 4]]).astype('float32') + x1 = paddle.imperative.to_variable(x) + + out1 = paddle.log1p(x1) + print(out1.numpy()) + # [[0.6931472 1.0986123] + # [1.3862944 1.609438 ]] + diff --git a/doc/paddle/api/paddle/tensor/math/logsumexp_cn.rst b/doc/paddle/api/paddle/tensor/math/logsumexp_cn.rst index a339972f9c24ebacdd555a3f04580957e2ad01a8..c95d8d611840f53c99f2205dad88139a0633694f 100644 --- a/doc/paddle/api/paddle/tensor/math/logsumexp_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/logsumexp_cn.rst @@ -3,52 +3,35 @@ logsumexp ------------------------------- -.. py:function:: paddle.tensor.math.logsumexp(x, dim=None, keepdim=False, out=None, name=None) +.. py:function:: paddle.tensor.math.logsumexp(x, axis=None, keepdim=False, name=None) -:alias_main: paddle.logsumexp -:alias: paddle.logsumexp,paddle.tensor.logsumexp,paddle.tensor.math.logsumexp - - - -该OP对输入Tensor的元素以e为底做指数运算，然后根据指定维度做求和之后取自然对数 +该OP沿着 ``axis`` 计算 ``x`` 的以e为底的指数的和的自然对数。计算公式如下： .. math:: logsumexp(x) = \log\sum exp(x) -参数： - - **x** （Variable）- 输入变量为多维Tensor或LoDTensor，支持数据类型为float32，float64 - - **dim** （list | int ，可选）- 求和运算的维度。如果为None，则计算所有元素的和并返回包含单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将变为 :math:`rank+dim[i]` ，默认值为None。 - - **keep_dim** （bool）- 是否在输出Tensor中保留减小的维度。如 keep_dim 为true，否则结果张量的维度将比输入张量小，默认值为False。 - - **out** （Variable ， 可选）- 显示指定的输出变量 - - **name** （str ， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 +参数 +:::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64 。 + - axis (int|list|tuple, 可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是int、list(int)、tuple(int)。如果 ``axis`` 包含多个维度，则沿着 ``axis`` 中的所有轴进行计算。``axis`` 或者其中的元素值应该在范围[-D, D)内，D是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于0，则等价于 :math:`axis + D` 。如果 ``axis`` 是None，则对 ``x`` 的全部元素计算平均值。默认值为None。 + - keepdim (bool, 可选) - 是否在输出Tensor中保留减小的维度。如果 ``keepdim`` 为True，则输出Tensor和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为1)。否则，输出Tensor的形状会在 ``axis`` 上进行squeeze操作。默认值为False。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回： Tensor，数据类型和输入数据类型一致。 +返回 +:::::::::: + ``Tensor`` ，沿着 ``axis`` 进行logsumexp计算的结果，数据类型和 ``x`` 相同。 -返回类型：Variable +代码示例 +:::::::::: -**代码示例1** - -.. code-block:: python +.. code-block:: python import paddle - import paddle.fluid as fluid import numpy as np - with fluid.dygraph.guard(): - np_x = np.random.uniform(0.1, 1, [10]).astype(np.float32) - x = fluid.dygraph.to_variable(np_x) - print(paddle.logsumexp(x).numpy()) - -**代码示例2** - -.. code-block:: python - - import paddle - import paddle.fluid as fluid - import numpy as np + paddle.disable_static() - with fluid.dygraph.guard(): - np_x = np.random.uniform(0.1, 1, [2, 3, 4]).astype(np.float32) - x = fluid.dygraph.to_variable(np_x) - print(paddle.logsumexp(x, dim=1).numpy()) - print(paddle.logsumexp(x, dim=[0, 2]).numpy()) + x = np.array([[-1.5, 0., 2.], [3., 1.2, -2.4]]) + x = paddle.to_tensor(x) + out1 = paddle.logsumexp(x) # [3.4691226] + out2 = paddle.logsumexp(x, 1) # [2.15317821, 3.15684602] diff --git a/doc/paddle/api/paddle/tensor/math/max_cn.rst b/doc/paddle/api/paddle/tensor/math/max_cn.rst index 24eb34761ef45323fa211f954bdf77b4d8c9d020..e3f1620fa1064f0db21f5fc308cd31521da95354 100644 --- a/doc/paddle/api/paddle/tensor/math/max_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/max_cn.rst @@ -1,60 +1,64 @@ - .. _cn_api_paddle_tensor_max: max ------------------------------- -.. py:function:: paddle.tensor.max(input, dim=None, keep_dim=False, out=None, name=None) +.. py:function:: paddle.tensor.max(x, axis=None, keepdim=False, name=None) :alias_main: paddle.max :alias: paddle.max,paddle.tensor.max,paddle.tensor.math.max -:update_api: paddle.fluid.layers.reduce_max - - -该OP是对指定维度上的Tensor元素求最大值运算，并输出相应的计算结果。等价于 :ref:`cn_api_fluid_layers_reduce_max` +该OP是对指定维度上的Tensor元素求最大值运算，并输出相应的计算结果。 -参数： - - **input** （Variable）- 输入变量为多维Tensor或LoDTensor，支持数据类型为float32，float64，int32，int64。 - - **dim** （list | int ，可选）- 求最大值运算的维度。如果为None，则计算所有元素的最大值并返回包含单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将变为 :math:`rank+dim[i]` ，默认值为None。 - - **keep_dim** （bool）- 是否在输出Tensor中保留减小的维度。如 keep_dim 为true，否则结果张量的维度将比输入张量小，默认值为False。 - - **out** (Variable， 可选) - 指定算子输出结果的LoDTensor/Tensor，可以是程序中已经创建的任何Variable。默认值为None，此时将创建新的Variable来保存输出结果。 - - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 +参数 +::::::::: + - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。 + - **axis** （list | int ，可选）- 求最大值运算的维度。如果为None，则计算所有元素的最大值并返回包含单个元素的Tensor变量，否则必须在 :math:`[-x.ndim, x.ndim]` 范围内。如果 :math:`axis[i] <0` ，则维度将变为 :math:`x.ndim+axis[i]` ，默认值为None。 + - **keepdim** （bool）- 是否在输出Tensor中保留减小的维度。如果keepdim 为 False，结果张量的维度将比输入张量的小，默认值为False。 + - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -返回： 在指定dim上进行求最大值运算的Tensor，数据类型和输入数据类型一致。 +返回 +::::::::: + Tensor, 在指定axis上进行求最大值运算的Tensor，数据类型和输入数据类型一致。 -返回类型： 变量（Variable） -**代码示例** +代码示例 +:::::::::: .. code-block:: python + import numpy as np import paddle - import paddle.fluid as fluid - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - x = fluid.data(name='x', shape=[2, 4], dtype='float32') - # paddle.max 等价于 paddle.tensor.max - paddle.max(x) # [0.9] - paddle.max(x, dim=0) # [0.2, 0.3, 0.6, 0.9] - paddle.max(x, dim=-1) # [0.9, 0.7] - paddle.max(x, dim=1, keep_dim=True) # [[0.9], [0.7]] - - # y是一个shape为[2, 2, 2]的Tensor，元素如下: - # [[[1.0, 2.0], [3.0, 4.0]], - # [[5.0, 6.0], [7.0, 8.0]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') - paddle.max(y, dim=[1, 2]) # [4.0, 8.0] - paddle.max(y, dim=[0, 1]) # [7.0, 8.0] - - - - - - - - + paddle.disable_static() + + # data_x is a variable with shape [2, 4] + # the axis is a int element + data_x = np.array([[0.2, 0.3, 0.5, 0.9], + [0.1, 0.2, 0.6, 0.7]]) + x = paddle.to_variable(data_x) + result1 = paddle.max(x) + print(result1.numpy()) + #[0.9] + result2 = paddle.max(x, axis=0) + print(result2.numpy()) + #[0.2 0.3 0.6 0.9] + result3 = paddle.max(x, axis=-1) + print(result3.numpy()) + #[0.9 0.7] + result4 = paddle.max(x, axis=1, keepdim=True) + print(result4.numpy()) + #[[0.9] + # [0.7]] + + # data_y is a variable with shape [2, 2, 2] + # the axis is list + data_y = np.array([[[1.0, 2.0], [3.0, 4.0]], + [[5.0, 6.0], [7.0, 8.0]]]) + y = paddle.to_variable(data_y) + result5 = paddle.max(y, axis=[1, 2]) + print(result5.numpy()) + #[4. 8.] + result6 = paddle.max(y, axis=[0, 1]) + print(result6.numpy()) + #[7. 8.] diff --git a/doc/paddle/api/paddle/tensor/math/min_cn.rst b/doc/paddle/api/paddle/tensor/math/min_cn.rst index d3417080c79bcc5df682feff99fd29c8d4a1057f..7231c1b20519c2fb807a05d6d35354177763830e 100644 --- a/doc/paddle/api/paddle/tensor/math/min_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/min_cn.rst @@ -3,57 +3,61 @@ min ------------------------------- -.. py:function:: paddle.tensor.min(input, dim=None, keep_dim=False, out=None, name=None) +.. py:function:: paddle.tensor.min(x, axis=None, keepdim=False, name=None) :alias_main: paddle.min :alias: paddle.min,paddle.tensor.min,paddle.tensor.math.min -:update_api: paddle.fluid.layers.reduce_min +该OP是对指定维度上的Tensor元素求最小值运算，并输出相应的计算结果。 +参数 +::::::::: + - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。 + - **axis** （list | int ，可选）- 求最小值运算的维度。如果为None，则计算所有元素的最小值并返回包含单个元素的Tensor变量，否则必须在 :math:`[−x.ndim, x.ndim]` 范围内。如果 :math:`axis[i] < 0` ，则维度将变为 :math:`x.ndim+axis[i]` ，默认值为None。 + - **keepdim** （bool）- 是否在输出Tensor中保留减小的维度。如果keepdim 为False，结果张量的维度将比输入张量的小，默认值为False。 + - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -该OP是对指定维度上的Tensor元素求最小值运算，并输出相应的计算结果。等价于 :ref:`cn_api_fluid_layers_reduce_min` +返回 +::::::::: + Tensor，在指定axis上进行求最小值运算的Tensor，数据类型和输入数据类型一致。 -参数： - - **input** （Variable）- 输入变量为多维Tensor或LoDTensor，支持数据类型为float32，float64，int32，int64。 - - **dim** （list | int ，可选）- 求最小值运算的维度。如果为None，则计算所有元素的最小值并返回包含单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将变为 :math:`rank+dim[i]` ，默认值为None。 - - **keep_dim** （bool）- 是否在输出Tensor中保留减小的维度。如 keep_dim 为true，否则结果张量的维度将比输入张量小，默认值为False。 - - **out** (Variable， 可选) - 指定算子输出结果的LoDTensor/Tensor，可以是程序中已经创建的任何Variable。默认值为None，此时将创建新的Variable来保存输出结果。 - - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 - -返回： 在指定dim上进行求最小值运算的Tensor，数据类型和输入数据类型一致。 - -返回类型： 变量（Variable） - -**代码示例** +代码示例 +:::::::::: .. code-block:: python + import numpy as np import paddle - import paddle.fluid as fluid - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - x = fluid.data(name='x', shape=[2, 4], dtype='float32') - # paddle.min 等价于 paddle.tensor.min - paddle.min(x) # [0.1] - paddle.min(x, dim=0) # [0.1, 0.2, 0.5, 0.7] - paddle.min(x, dim=-1) # [0.2, 0.1] - paddle.min(x, dim=1, keep_dim=True) # [[0.2], [0.1]] - - # y是一个shape为[2, 2, 2]的Tensor，元素如下: - # [[[1.0, 2.0], [3.0, 4.0]], - # [[5.0, 6.0], [7.0, 8.0]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') - paddle.min(y, dim=[1, 2]) # [1.0, 5.0] - paddle.min(y, dim=[0, 1]) # [1.0, 2.0] - - - - - - - - + paddle.disable_static() + + # data_x is a variable with shape [2, 4] + # the axis is a int element + data_x = np.array([[0.2, 0.3, 0.5, 0.9], + [0.1, 0.2, 0.6, 0.7]]) + x = paddle.to_variable(data_x) + result1 = paddle.min(x) + print(result1.numpy()) + #[0.1] + result2 = paddle.min(x, axis=0) + print(result2.numpy()) + #[0.1 0.2 0.5 0.7] + result3 = paddle.min(x, axis=-1) + print(result3.numpy()) + #[0.2 0.1] + result4 = paddle.min(x, axis=1, keepdim=True) + print(result4.numpy()) + #[[0.2] + # [0.1]] + + # data_y is a variable with shape [2, 2, 2] + # the axis is list + data_y = np.array([[[1.0, 2.0], [3.0, 4.0]], + [[5.0, 6.0], [7.0, 8.0]]]) + y = paddle.to_variable(data_y) + result5 = paddle.min(y, axis=[1, 2]) + print(result5.numpy()) + #[1. 5.] + result6 = paddle.min(y, axis=[0, 1]) + print(result6.numpy()) + #[1. 2.] diff --git a/doc/paddle/api/paddle/tensor/math/mod_cn.rst b/doc/paddle/api/paddle/tensor/math/mod_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..b7f34c81e5937ac5ed96e7b63a9d2cc080c5b01d --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/mod_cn.rst @@ -0,0 +1,7 @@ +.. _cn_api_tensor_cn_mod: + +mod +------------------------------- +:doc_source: paddle.tensor.remainder + + diff --git a/doc/paddle/api/paddle/tensor/math/prod_cn.rst b/doc/paddle/api/paddle/tensor/math/prod_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..64058ada576905be353bdb8f97ad50369db56688 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/prod_cn.rst @@ -0,0 +1,69 @@ +.. _cn_api_tensor_cn_prod: + +prod +------------------------------- + +.. py:function:: paddle.prod(x, axis=None, keepdim=False, dtype=None, name=None) + + + +对指定维度上的Tensor元素进行求乘积运算，并输出相应的计算结果。 + +参数： + - **x** (Tensor) - 输入的 `Tensor` ，数据类型为：float32、float64、int32、int64。 + - **axis** (int|list|tuple，可选) - 求乘积运算的维度。如果是None，则计算所有元素的乘积并返回包含单个元素的Tensor，否则该参数必须在 :math:`[-x.ndim, x.ndim)` 范围内。如果 :math:`axis[i] < 0` ，则维度将变为 :math:`x.ndim + axis[i]` ，默认为None。 + - **keepdim** (bool，可选) - 是否在输出 `Tensor` 中保留减小的维度。如 `keepdim` 为True，否则结果张量的维度将比输入张量小，默认值为False。 + - **dtype** (str，可选) - 输出Tensor的数据类型，支持int32、int64、float32、float64。如果指定了该参数，那么在执行操作之前，输入Tensor将被转换为dtype类型. 这对于防止数据类型溢出非常有用。若参数为空，则输出变量的数据类型和输入变量相同，默认为：None。 + - **name** （str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。 + +返回：指定axis上累乘的结果的Tensor。 + + +**代码示例**： + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + # the axis is a int element + data_x = np.array([[0.2, 0.3, 0.5, 0.9], + [0.1, 0.2, 0.6, 0.7]]).astype(np.float32) + x = paddle.to_tensor(data_x) + out1 = paddle.prod(x) + print(out1.numpy()) + # [0.0002268] + + out2 = paddle.prod(x, -1) + print(out2.numpy()) + # [0.027 0.0084] + + out3 = paddle.prod(x, 0) + print(out3.numpy()) + # [0.02 0.06 0.3 0.63] + print(out3.numpy().dtype) + # float32 + + out4 = paddle.prod(x, 0, keepdim=True) + print(out4.numpy()) + # [[0.02 0.06 0.3 0.63]] + + out5 = paddle.prod(x, 0, dtype='int64') + print(out5.numpy()) + # [0 0 0 0] + print(out5.numpy().dtype) + # int64 + + # the axis is list + data_y = np.array([[[1.0, 2.0], [3.0, 4.0]], + [[5.0, 6.0], [7.0, 8.0]]]) + y = paddle.to_tensor(data_y) + out6 = paddle.prod(y, [0, 1]) + print(out6.numpy()) + # [105. 384.] + + out7 = paddle.prod(y, (1, 2)) + print(out7.numpy()) + # [ 24. 1680.] diff --git a/doc/paddle/api/paddle/tensor/math/remainder_cn.rst b/doc/paddle/api/paddle/tensor/math/remainder_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..ccf124eb8a344c65e216f368d8b748c20c484a0f --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/remainder_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_tensor_remainder: + +remainder +------------------------------- + +.. py:function:: paddle.remainder(x, y, name=None) + +该OP是逐元素取模算子，输入 ``x`` 与输入 ``y`` 逐元素取模，并将各个位置的输出元素保存到返回结果中。 +输入 ``x`` 与输入 ``y`` 必须可以广播为相同形状, 关于广播规则，请参考 :ref:`use_guide_broadcasting` + +等式为： + +.. math:: + Out = X \% Y + +- :math:`X` ：多维Tensor。 +- :math:`Y` ：多维Tensor。 + +参数： + - x（Tensor）- 多维Tensor。数据类型为float32 、float64、int32或int64。 + - y（Tensor）- 多维Tensor。数据类型为float32 、float64、int32或int64。 + - name（str，可选）- 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + + +返回： 多维 Tensor， 数据类型与 ``x`` 相同，维度为广播后的形状。 + +返回类型： Tensor + + +**代码示例** + +.. code-block:: python + + import paddle + import numpy as np + paddle.disable_static() + np_x = np.array([2, 3, 8, 7]) + np_y = np.array([1, 5, 3, 3]) + x = paddle.to_tensor(np_x) + y = paddle.to_tensor(np_y) + z = paddle.remainder(x, y) + print(z.numpy()) # [0, 3, 2, 1] \ No newline at end of file diff --git a/doc/paddle/api/paddle/tensor/math/sign_cn.rst b/doc/paddle/api/paddle/tensor/math/sign_cn.rst index 5559e7a7bef67ed07aa58e3162e6c501867a803f..e1443fc2dfa3aedf65a2997f6b10bd91593d6325 100644 --- a/doc/paddle/api/paddle/tensor/math/sign_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/sign_cn.rst @@ -1,32 +1,30 @@ -.. _cn_api_fluid_layers_sign: +.. _cn_api_tensor_sign: sign ------------------------------- -.. py:function:: paddle.fluid.layers.sign(x) - -:alias_main: paddle.sign -:alias: paddle.sign,paddle.tensor.sign,paddle.tensor.math.sign -:old_api: paddle.fluid.layers.sign - - +.. py:function:: paddle.sign(x, name=None) 此OP对输入x中每个元素进行正负判断，并且输出正负判断值：1代表正，-1代表负，0代表零。 参数： - - **x** (Variable|numpy.ndarray) – 进行正负值判断的多维Tensor或者是多维的numpy数组，数据类型为 float32，float64。 + - **x** (Tensor) – 进行正负值判断的多维Tensor，数据类型为 float16， float32或float64。 + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -返回：输出正负号Tensor，数据的shape大小和输入x的数据shape一致。 +返回：输出正负号Tensor，数据的shape大小及数据类型和输入 ``x`` 一致。 -返回类型：Variable，数据类型和输入数据类型一致。 +返回类型：Tensor **代码示例** .. code-block:: python - import paddle.fluid as fluid import numpy as np + import paddle - data = fluid.layers.sign(np.array([3.0, 0.0, -2.0], dtype='float32')) - # data=[1.0, 0.0, -1.0] + data = np.array([3.0, 0.0, -2.0, 1.7], dtype='float32') + paddle.disable_static() + x = paddle.to_tensor(data) + out = paddle.sign(x=x) + print(out) # [1.0, 0.0, -1.0, 1.0] diff --git a/doc/paddle/api/paddle/tensor/math/sqrt_cn.rst b/doc/paddle/api/paddle/tensor/math/sqrt_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..779ab45fbf975d0cc9538cd7f2d68f0194e8bc64 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/math/sqrt_cn.rst @@ -0,0 +1,55 @@ +.. _cn_api_fluid_layers_sqrt: + +sqrt +------------------------------- + +.. py:function:: paddle.fluid.layers.sqrt(x, name=None) + + + + +计算输入的算数平方根。 + +.. math:: out=\sqrt x=x^{1/2} + +.. note:: + 请确保输入中的数值是非负数。 + +参数: + + - **x** (Variable) - 支持任意维度的Tensor。数据类型为float32，float64或float16。 + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：返回类型为Variable(Tensor|LoDTensor)， 数据类型同输入一致。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle.fluid as fluid + + inputs = fluid.layers.data(name="x", shape = [3], dtype='float32') + output = fluid.layers.sqrt(inputs) + + exe = fluid.Executor(fluid.CPUPlace()) + exe.run(fluid.default_startup_program()) + + img = np.array([0, 9, 36]).astype(np.float32) + + res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output]) + print(res) + # [array([0., 3., 6.], dtype=float32)] + + + + + + + + + + + + + diff --git a/doc/paddle/api/paddle/tensor/math/sum_cn.rst b/doc/paddle/api/paddle/tensor/math/sum_cn.rst old mode 100755 new mode 100644 diff --git a/doc/paddle/api/paddle/tensor/math/tanh_cn.rst b/doc/paddle/api/paddle/tensor/math/tanh_cn.rst index c5fbd21242439402ebda6b4fcd5e6aedec699aa7..ee81756c3cf07006510b44204f56ebdc43ffa442 100644 --- a/doc/paddle/api/paddle/tensor/math/tanh_cn.rst +++ b/doc/paddle/api/paddle/tensor/math/tanh_cn.rst @@ -1,12 +1,9 @@ -.. _cn_api_fluid_layers_tanh: +.. _cn_api_tensor_tanh: tanh ------------------------------- -.. py:function:: paddle.fluid.layers.tanh(x, name=None) - - - +.. py:function:: paddle.tanh(x, name=None) tanh 激活函数 @@ -14,33 +11,27 @@ tanh 激活函数 .. math:: out = \frac{e^{x} - e^{-x}}{e^{x} + e^{-x}} - 参数: - - **x** - Tanh算子的输入 - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 + - **x** (Tensor) - Tanh算子的输入, 多维Tensor，数据类型为 float16，float32或float64。 + - **name** (str, 可选) - 该层名称（可选，默认为None）。具体用法请参见 :ref:`api_guide_Name`。 -返回: 张量(Tensor) +返回: tanh的输出Tensor，和输入有着相同类型和shape。 -返回类型: 变量(Variable) +返回类型: Tensor **代码示例**： .. code-block:: python - import paddle.fluid as fluid - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.tanh(data) - - - - - - - - - - + import paddle + import numpy as np + paddle.disable_static() + x_data = np.array([-0.4, -0.2, 0.1, 0.3]) + x = paddle.to_tensor(x_data) + out = paddle.tanh(x) + print(out.numpy()) + # [-0.37994896 -0.19737532 0.09966799 0.29131261] diff --git a/doc/paddle/api/paddle/tensor/random/bernoulli_cn.rst b/doc/paddle/api/paddle/tensor/random/bernoulli_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..a18096b54472967d22d7707b2198581770569a0e --- /dev/null +++ b/doc/paddle/api/paddle/tensor/random/bernoulli_cn.rst @@ -0,0 +1,49 @@ +.. _cn_api_tensor_bernoulli: + +bernoulli +------------------------------- + +.. py:function:: paddle.bernoulli(x, name=None) + + + + +该OP以输入 ``x`` 为概率，生成一个伯努利分布（0-1分布）的Tensor，输出Tensor的形状和数据类型与输入 ``x`` 相同。 + +.. math:: + out_i \sim Bernoulli(p = x_i) + +参数： + - **x** (Tensor) - 输入的概率值。数据类型为 ``float32`` 、``float64`` . + - **name** (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回： + Tensor：伯努利分布的随机Tensor，形状和数据类型为与输入 ``x`` 相同。 + + +**代码示例**： + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + + x = paddle.rand([2, 3]) + print(x.numpy()) + # [[0.11272584 0.3890902 0.7730957 ] + # [0.10351662 0.8510418 0.63806665]] + + out = paddle.bernoulli(x) + print(out.numpy()) + # [[0. 0. 1.] + # [0. 0. 1.]] + + + + + + + + diff --git a/doc/paddle/api/paddle/tensor/random/normal_cn.rst b/doc/paddle/api/paddle/tensor/random/normal_cn.rst index ac57976ad7b741cd133014372b99b4fd801d0c13..bcefb2f566e339cbc7fa220f33cda0f7e9e21749 100644 --- a/doc/paddle/api/paddle/tensor/random/normal_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/normal_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_tensor_random_normal: +.. _cn_api_tensor_normal: normal ------------------------------- @@ -36,13 +36,13 @@ normal paddle.disable_static() out1 = paddle.normal(shape=[2, 3]) - # [[ 0.17501129 0.32364586 1.561118 ] # random - # [-1.7232178 1.1545963 -0.76156676]] # random + # [[ 0.17501129 0.32364586 1.561118 ] + # [-1.7232178 1.1545963 -0.76156676]] mean_tensor = paddle.to_tensor(np.array([1.0, 2.0, 3.0])) out2 = paddle.normal(mean=mean_tensor) - # [ 0.18644847 -1.19434458 3.93694787] # random + # [ 0.18644847 -1.19434458 3.93694787] std_tensor = paddle.to_tensor(np.array([1.0, 2.0, 3.0])) out3 = paddle.normal(mean=mean_tensor, std=std_tensor) - # [1.00780561 3.78457445 5.81058198] # random + # [1.00780561 3.78457445 5.81058198] diff --git a/doc/paddle/api/paddle/tensor/random/rand_cn.rst b/doc/paddle/api/paddle/tensor/random/rand_cn.rst index 5045d6d4f9e24b27954b84c7cf46abb6e94b835b..36fc3f1a6fdecf051a212e7099382e75c859702d 100644 --- a/doc/paddle/api/paddle/tensor/random/rand_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/rand_cn.rst @@ -5,6 +5,11 @@ rand .. py:function:: paddle.rand(shape, dtype=None, name=None) +:alias_main: paddle.rand +:alias: paddle.tensor.rand, paddle.tensor.random.rand + + + 该OP返回符合均匀分布的，范围在[0, 1)的Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 @@ -17,6 +22,11 @@ rand :::::::::: Tensor: 符合均匀分布的范围为[0, 1)的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 +抛出异常 +:::::::::: + - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 + - ``TypeError`` - 如果 ``dtype`` 不是float32、float64。 + 示例代码 :::::::::: @@ -25,25 +35,25 @@ rand import paddle import numpy as np - paddle.disable_static() + paddle.enable_imperative() # example 1: attr shape is a list which doesn't contain Tensor. - out1 = paddle.rand(shape=[2, 3]) - # [[0.451152 , 0.55825245, 0.403311 ], # random - # [0.22550228, 0.22106001, 0.7877319 ]] # random + result_1 = paddle.rand(shape=[2, 3]) + # [[0.451152 , 0.55825245, 0.403311 ], + # [0.22550228, 0.22106001, 0.7877319 ]] # example 2: attr shape is a list which contains Tensor. - dim1 = paddle.full([1], 2, "int64") - dim2 = paddle.full([1], 3, "int32") - out2 = paddle.rand(shape=[dim1, dim2, 2]) - # [[[0.8879919 , 0.25788337], # random - # [0.28826773, 0.9712097 ], # random - # [0.26438272, 0.01796806]], # random - # [[0.33633623, 0.28654453], # random - # [0.79109055, 0.7305809 ], # random - # [0.870881 , 0.2984597 ]]] # random + dim_1 = paddle.fill_constant([1], "int64", 2) + dim_2 = paddle.fill_constant([1], "int32", 3) + result_2 = paddle.rand(shape=[dim_1, dim_2, 2]) + # [[[0.8879919 0.25788337] + # [0.28826773 0.9712097 ] + # [0.26438272 0.01796806]] + # [[0.33633623 0.28654453] + # [0.79109055 0.7305809 ] + # [0.870881 0.2984597 ]]] # example 3: attr shape is a Tensor, the data type must be int64 or int32. - shape_tensor = paddle.to_tensor(np.array([2, 3])) - out2 = paddle.rand(shape_tensor) - # [[0.22920267, 0.841956 , 0.05981819], # random - # [0.4836288 , 0.24573246, 0.7516129 ]] # random + var_shape = paddle.imperative.to_variable(np.array([2, 3])) + result_3 = paddle.rand(var_shape) + # [[0.22920267 0.841956 0.05981819] + # [0.4836288 0.24573246 0.7516129 ]] diff --git a/doc/paddle/api/paddle/tensor/random/randint_cn.rst b/doc/paddle/api/paddle/tensor/random/randint_cn.rst index bac8502dc0b3e0cc6546e8cb4d737b2e399f1d80..e2ef78ff5d2294b795bce9e136f039a5270a15dd 100644 --- a/doc/paddle/api/paddle/tensor/random/randint_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/randint_cn.rst @@ -1,10 +1,15 @@ -.. _cn_api_tensor_random_randint: +.. _cn_api_tensor_randint: randint ------------------------------- .. py:function:: paddle.randint(low=0, high=None, shape=[1], dtype=None, name=None) +:alias_main: paddle.randint +:alias: paddle.tensor.randint, paddle.tensor.random.randint + + + 该OP返回服从均匀分布的、范围在[``low``, ``high``)的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。当 ``high`` 为None时（默认），均匀采样的区间为[0, ``low``)。 参数 @@ -19,6 +24,12 @@ randint :::::::::: Tensor：从区间[``low``，``high``)内均匀分布采样的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 +抛出异常 +:::::::::: + - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 + - ``TypeError`` - 如果 ``dtype`` 不是int32、int64。 + - ``ValueError`` - 如果 ``high`` 不大于 ``low``；或者 ``high`` 为None，且 ``low`` 不大于0。 + 代码示例 ::::::::::: @@ -27,34 +38,35 @@ randint import paddle import numpy as np - paddle.disable_static() + paddle.enable_imperative() # example 1: # attr shape is a list which doesn't contain Tensor. - out1 = paddle.randint(low=-5, high=5, shape=[3]) - # [0, -3, 2] # random + result_1 = paddle.randint(low=-5, high=5, shape=[3]) + # [0, -3, 2] # example 2: # attr shape is a list which contains Tensor. - dim1 = paddle.full([1], 2, "int64") - dim2 = paddle.full([1], 3, "int32") - out2 = paddle.randint(low=-5, high=5, shape=[dim1, dim2], dtype="int32") - # [[0, -1, -3], # random - # [4, -2, 0]] # random + dim_1 = paddle.fill_constant([1], "int64", 2) + dim_2 = paddle.fill_constant([1], "int32", 3) + result_2 = paddle.randint(low=-5, high=5, shape=[dim_1, dim_2], dtype="int32") + print(result_2.numpy()) + # [[ 0, -1, -3], + # [ 4, -2, 0]] # example 3: # attr shape is a Tensor - shape_tensor = paddle.to_tensor(np.array([3])) - out3 = paddle.randint(low=-5, high=5, shape=shape_tensor) - # [-2, 2, 3] # random + var_shape = paddle.imperative.to_variable(np.array([3])) + result_3 = paddle.randint(low=-5, high=5, shape=var_shape) + # [-2, 2, 3] # example 4: - # data type is int32 - out4 = paddle.randint(low=-5, high=5, shape=[3], dtype='int32') - # [-5, 4, -4] # random + # date type is int32 + result_4 = paddle.randint(low=-5, high=5, shape=[3], dtype='int32') + # [-5, 4, -4] # example 5: # Input only one parameter # low=0, high=10, shape=[1], dtype='int64' - out5 = paddle.randint(10) - # [7] # random + result_5 = paddle.randint(10) + # [7] diff --git a/doc/paddle/api/paddle/tensor/random/randn_cn.rst b/doc/paddle/api/paddle/tensor/random/randn_cn.rst index fa9b18fb9513c241a539fdc7bdc23b74da8363ca..e465b0c75eb5dbb06386abfc5d6f41746b6e967b 100644 --- a/doc/paddle/api/paddle/tensor/random/randn_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/randn_cn.rst @@ -5,6 +5,11 @@ randn .. py:function:: paddle.randn(shape, dtype=None, name=None) +:alias_main: paddle.randn +:alias: paddle.tensor.randn, paddle.tensor.random.randn + + + 该OP返回符合标准正态分布（均值为0，标准差为1的正态随机分布）的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 @@ -17,6 +22,11 @@ randn :::::::::: Tensor：符合标准正态分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 +抛出异常 +:::::::::: + - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 + - ``TypeError`` - 如果 ``dtype`` 不是float32、float64。 + 示例代码 :::::::::: @@ -25,26 +35,26 @@ randn import paddle import numpy as np - paddle.disable_static() + paddle.enable_imperative() # example 1: attr shape is a list which doesn't contain Tensor. - out1 = paddle.randn(shape=[2, 3]) - # [[-2.923464 , 0.11934398, -0.51249987], # random - # [ 0.39632758, 0.08177969, 0.2692008 ]] # random + result_1 = paddle.randn(shape=[2, 3]) + # [[-2.923464 0.11934398 -0.51249987] + # [ 0.39632758 0.08177969 0.2692008 ]] # example 2: attr shape is a list which contains Tensor. - dim1 = paddle.full([1], 2, "int64") - dim2 = paddle.full([1], 3, "int32") - out2 = paddle.randn(shape=[dim1, dim2, 2]) - # [[[-2.8852394 , -0.25898588], # random - # [-0.47420555, 0.17683524], # random - # [-0.7989969 , 0.00754541]], # random - # [[ 0.85201347, 0.32320443], # random - # [ 1.1399018 , 0.48336947], # random - # [ 0.8086993 , 0.6868893 ]]] # random + dim_1 = paddle.fill_constant([1], "int64", 2) + dim_2 = paddle.fill_constant([1], "int32", 3) + result_2 = paddle.randn(shape=[dim_1, dim_2, 2]) + # [[[-2.8852394 -0.25898588] + # [-0.47420555 0.17683524] + # [-0.7989969 0.00754541]] + # [[ 0.85201347 0.32320443] + # [ 1.1399018 0.48336947] + # [ 0.8086993 0.6868893 ]]] # example 3: attr shape is a Tensor, the data type must be int64 or int32. - shape_tensor = paddle.to_tensor(np.array([2, 3])) - out3 = paddle.randn(shape_tensor) - # [[-2.878077 , 0.17099959, 0.05111201] # random - # [-0.3761474, -1.044801 , 1.1870178 ]] # random + var_shape = paddle.imperative.to_variable(np.array([2, 3])) + result_3 = paddle.randn(var_shape) + # [[-2.878077 0.17099959 0.05111201] + # [-0.3761474 -1.044801 1.1870178 ]] diff --git a/doc/paddle/api/paddle/tensor/random/randperm_cn.rst b/doc/paddle/api/paddle/tensor/random/randperm_cn.rst index c78212af8b6984fffab96dd2aede895d9f342d5d..d3c756a0fc9ded21c9b78d95dd532b9ba4aa26e9 100644 --- a/doc/paddle/api/paddle/tensor/random/randperm_cn.rst +++ b/doc/paddle/api/paddle/tensor/random/randperm_cn.rst @@ -5,6 +5,9 @@ randperm .. py:function:: paddle.randperm(n, dtype="int64", name=None) +:alias_main: paddle.randperm +:alias: paddle.tensor.randperm, paddle.tensor.random.randperm + 该OP返回一个数值在0到n-1、随机排列的1-D Tensor，数据类型为 ``dtype``。 参数: @@ -17,17 +20,22 @@ randperm :::::::::: Tensor：一个数值在0到n-1、随机排列的1-D Tensor，数据类型为 ``dtype`` 。 +抛出异常 +:::::::::: + - ValueError - 如果 ``n`` 不大于0. + - TypeError - 如果 ``dtype`` 不是int32、int64、float32、float64. + 代码示例 :::::::::: -.. code-block:: python +.. code-block:: python import paddle - paddle.disable_static() + paddle.enable_imperative() - out1 = paddle.randperm(5) - # [4, 1, 2, 3, 0] # random + result_1 = paddle.randperm(5) + # [4 1 2 3 0] - out2 = paddle.randperm(7, 'int32') - # [1, 6, 2, 0, 4, 3, 5] # random + result_2 = paddle.randperm(7, 'int32') + # [1 6 2 0 4 3 5] diff --git a/doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst b/doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst deleted file mode 100644 index d379107d66ca0e024427a3cf3eb91b161ee1425e..0000000000000000000000000000000000000000 --- a/doc/paddle/api/paddle/tensor/random/standard_normal_cn.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _cn_api_tensor_random_standard_normal: - -standard_normal -------------------------------- - -.. py:function:: paddle.standard_normal(shape, dtype=None, name=None) - -该OP返回符合标准正态分布（均值为0，标准差为1的正态随机分布）的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 - -参数 -:::::::::: - - **shape** (list|tuple|Tensor) - 生成的随机Tensor的形状。如果 ``shape`` 是list、tuple，则其中的元素可以是int，或者是形状为[1]且数据类型为int32、int64的Tensor。如果 ``shape`` 是Tensor，则是数据类型为int32、int64的1-D Tensor。 - - **dtype** (str|np.dtype|core.VarDesc.VarType, 可选) - 输出Tensor的数据类型，支持float32、float64。当该参数值为None时， 输出Tensor的数据类型为float32。默认值为None. - - **name** (str, 可选) - 输出的名字。一般无需设置，默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。 - -返回 -:::::::::: - Tensor：符合标准正态分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 - -示例代码 -:::::::::: - -.. code-block:: python - - import paddle - import numpy as np - - paddle.disable_static() - - # example 1: attr shape is a list which doesn't contain Tensor. - out1 = paddle.standard_normal(shape=[2, 3]) - # [[-2.923464 , 0.11934398, -0.51249987], # random - # [ 0.39632758, 0.08177969, 0.2692008 ]] # random - - # example 2: attr shape is a list which contains Tensor. - dim1 = paddle.full([1], 2, "int64") - dim2 = paddle.full([1], 3, "int32") - out2 = paddle.standard_normal(shape=[dim1, dim2, 2]) - # [[[-2.8852394 , -0.25898588], # random - # [-0.47420555, 0.17683524], # random - # [-0.7989969 , 0.00754541]], # random - # [[ 0.85201347, 0.32320443], # random - # [ 1.1399018 , 0.48336947], # random - # [ 0.8086993 , 0.6868893 ]]] # random - - # example 3: attr shape is a Tensor, the data type must be int64 or int32. - shape_tensor = paddle.to_tensor(np.array([2, 3])) - out3 = paddle.standard_normal(shape_tensor) - # [[-2.878077 , 0.17099959, 0.05111201] # random - # [-0.3761474, -1.044801 , 1.1870178 ]] # random diff --git a/doc/paddle/api/paddle/tensor/random/uniform_cn.rst b/doc/paddle/api/paddle/tensor/random/uniform_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..f5996a72d4f88a38ad0d71fc84b002c3a69bbd2d --- /dev/null +++ b/doc/paddle/api/paddle/tensor/random/uniform_cn.rst @@ -0,0 +1,77 @@ +.. _cn_api_tensor_uniform: + +uniform +------------------------------- + +.. py:function:: paddle.uniform(shape, dtype='float32', min=-1.0, max=1.0, seed=0, name=None) + + + + +该OP返回数值服从范围[``min``, ``max``)内均匀分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 + +:: + + 示例1: + 给定： + shape=[1,2] + 则输出为： + result=[[0.8505902, 0.8397286]] + +参数： + - **shape** (list|tuple|Tensor) - 生成的随机Tensor的形状。如果 ``shape`` 是list、tuple，则其中的元素可以是int，或者是形状为[1]且数据类型为int32、int64的Tensor。如果 ``shape`` 是Tensor，则是数据类型为int32、int64的1-D Tensor。 + - **dtype** (str|np.dtype， 可选) - 输出Tensor的数据类型，支持float32、float64。默认值为float32。 + - **min** (float|int，可选) - 要生成的随机值范围的下限，min包含在范围中。支持的数据类型：float、int。默认值为-1.0。 + - **max** (float|int，可选) - 要生成的随机值范围的上限，max不包含在范围中。支持的数据类型：float、int。默认值为1.0。 + - **seed** (int，可选) - 随机种子，用于生成样本。0表示使用系统生成的种子。注意如果种子不为0，该操作符每次都生成同样的随机数。支持的数据类型：int。默认为 0。 + - **name** (str, 可选) - 输出的名字。一般无需设置，默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。 + +返回： + Tensor：数值服从范围[``min``, ``max``)内均匀分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。 + +抛出异常： + - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。 + - ``TypeError`` - 如果 ``dtype`` 不是float32、float64。 + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + + paddle.disable_static() + + # example 1: + # attr shape is a list which doesn't contain Tensor. + result_1 = paddle.uniform(shape=[3, 4]) + # [[ 0.84524226, 0.6921872, 0.56528175, 0.71690357], + # [-0.34646994, -0.45116323, -0.09902662, -0.11397249], + # [ 0.433519, 0.39483607, -0.8660099, 0.83664286]] + + # example 2: + # attr shape is a list which contains Tensor. + dim_1 = paddle.fill_constant([1], "int64", 2) + dim_2 = paddle.fill_constant([1], "int32", 3) + result_2 = paddle.uniform(shape=[dim_1, dim_2]) + # [[-0.9951253, 0.30757582, 0.9899647 ], + # [ 0.5864527, 0.6607096, -0.8886161 ]] + + # example 3: + # attr shape is a Tensor, the data type must be int64 or int32. + shape = np.array([2, 3]) + shape_tensor = paddle.to_tensor(shape) + + result_3 = paddle.uniform(shape_tensor) + # if shape_tensor's value is [2, 3] + # result_3 is: + # [[-0.8517412, -0.4006908, 0.2551912 ], + # [ 0.3364414, 0.36278176, -0.16085452]] + + + + + + + + diff --git a/doc/paddle/api/paddle/tensor/search/argmax_cn.rst b/doc/paddle/api/paddle/tensor/search/argmax_cn.rst index 157806c38000bd4ae1866e55e4ecbe5bd90e7882..d2fb738b4cd99c1cf6d458ed994aae2b7186f09d 100644 --- a/doc/paddle/api/paddle/tensor/search/argmax_cn.rst +++ b/doc/paddle/api/paddle/tensor/search/argmax_cn.rst @@ -3,7 +3,7 @@ argmax ------------------------------- -.. py:function:: paddle.argmax(x, axis=None, dtype=None, keepdim=False, name=None) +.. py:function:: paddle.argmax(x, axis=None, keepdim=False, dtype='int64', name=None) 该OP沿 ``axis`` 计算输入 ``x`` 的最大元素的索引。 @@ -12,8 +12,8 @@ argmax :::::::: - **x** （Tensor） - 输入的多维 ``Tensor`` ，支持的数据类型：float32、float64、int16、int32、int64、uint8。 - **axis** （int，可选） - 指定对输入Tensor进行运算的轴， ``axis`` 的有效范围是[-R, R），R是输入 ``x`` 的维度个数， ``axis`` 为负数时，进行计算的 ``axis`` 与 ``axis`` + R 一致。默认值为None, 将会对输入的 `x` 进行平铺展开，返回最大值的索引。 - - **dtype** （np.dtype|str）- 输出Tensor的数据类型，可选值为int32，int64，默认值为None，将返回int64类型的结果。 - **keepdim** （bool，可选）- 是否保留进行最大值索引操作的轴，默认值为False。 + - **dtype** （np.dtype|str，可选）- 输出Tensor的数据类型，可选值为int32，int64，默认值为int64，将返回int64类型的结果。 - **name** （str，可选） – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回 diff --git a/doc/paddle/api/paddle/tensor/search/argmin_cn.rst b/doc/paddle/api/paddle/tensor/search/argmin_cn.rst index 14082c452382ba2e7c17eb11306e190b087e0c70..4fd851764cbffe8a5ba93e3605034a9c55854e47 100644 --- a/doc/paddle/api/paddle/tensor/search/argmin_cn.rst +++ b/doc/paddle/api/paddle/tensor/search/argmin_cn.rst @@ -3,7 +3,7 @@ argmin ------------------------------- -.. py:function:: paddle.argmin(x, axis=None, dtype=None, keepdim=False, name=None) +.. py:function:: paddle.argmin(x, axis=None, keepdim=False, dtype='int64', name=None) 该OP沿 ``axis`` 计算输入 ``x`` 的最小元素的索引。 @@ -12,8 +12,8 @@ argmin :::::::: - **x** （Tensor） - 输入的多维 ``Tensor`` ，支持的数据类型：float32、float64、int16、int32、int64、uint8。 - **axis** （int，可选） - 指定对输入Tensor进行运算的轴， ``axis`` 的有效范围是[-R, R），R是输入 ``x`` 的维度个数， ``axis`` 为负数时，进行计算的 ``axis`` 与 ``axis`` + R 一致。默认值为None, 将会对输入的 `x` 进行平铺展开，返回最小值的索引。 - - **dtype** （np.dtype|str）- 输出Tensor的数据类型，可选值为int32，int64，默认值为None，将返回int64类型的结果。 - **keepdim** （bool，可选）- 是否保留进行最小值索引操作的轴，默认值为False。 + - **dtype** （np.dtype|str, 可选）- 输出Tensor的数据类型，可选值为int32，int64，默认值为'int64'，将返回int64类型的结果。 - **name** （str，可选） – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回 diff --git a/doc/paddle/api/paddle/tensor/search/index_select_cn.rst b/doc/paddle/api/paddle/tensor/search/index_select_cn.rst index 077baf49bd0af13faa889992b2d41ce7723ac574..fe60cbc5aec076d5e8c0c9235330fbecd33da432 100644 --- a/doc/paddle/api/paddle/tensor/search/index_select_cn.rst +++ b/doc/paddle/api/paddle/tensor/search/index_select_cn.rst @@ -7,21 +7,17 @@ index_select -该OP沿着指定轴 ``axis`` 对输入 ``x`` 进行索引，取 ``index`` 中指定的相应项，创建并返回到一个新的Tensor。这里 ``index`` 是一个 ``1-D`` Tensor。除 ``axis`` 轴外，返回的Tensor其余维度大小和输入 ``x``相等 ， ``axis`` 维度的大小等于 ``index`` 的大小。 +该OP沿着指定轴 ``axis`` 对输入 ``x`` 进行索引，取 ``index`` 中指定的相应项，创建并返回到一个新的Tensor。这里 ``index`` 是一个 ``1-D`` Tensor。除 ``axis`` 轴外，返回的Tensor其余维度大小和输入 ``x`` 相等 ， ``axis`` 维度的大小等于 ``index`` 的大小。 **参数**： - **x** （Tensor）– 输入Tensor。 ``x`` 的数据类型可以是float32，float64，int32，int64。 - - **index** （Tensor）– 包含索引下标的一维Tensor。 + - **index** （Tensor）– 包含索引下标的1-D Tensor。 - **axis** (int, 可选) – 索引轴，若未指定，则默认选取第0维。 - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 **返回**： -**Tensor**: 返回一个数据类型同输入的Tensor。 -抛出异常： - - ``TypeError`` - 当 ``x`` 或者 ``index`` 的类型不是Tensor。 - - ``TypeError`` - 当 ``x`` 的数据类型不是float32、float64、int32、int64其中之一或者 ``index`` 的数据类型不是int32、int64其中之一。 - **代码示例**： @@ -30,14 +26,14 @@ index_select import paddle import numpy as np - paddle.enable_imperative() # Now we are in imperative mode + paddle.disable_static() # Now we are in imperative mode data = np.array([[1.0, 2.0, 3.0, 4.0], [5.0, 6.0, 7.0, 8.0], [9.0, 10.0, 11.0, 12.0]]) - data_index = np.array([-1, 1, 1]).astype('int32') + data_index = np.array([0, 1, 1]).astype('int32') - x = paddle.imperative.to_variable(data) - index = paddle.imperative.to_variable(data_index) + x = paddle.to_tensor(data) + index = paddle.to_tensor(data_index) out_z1 = paddle.index_select(x=x, index=index) #[[1. 2. 3. 4.] # [5. 6. 7. 8.] diff --git a/doc/paddle/api/paddle/tensor/search/masked_select_cn.rst b/doc/paddle/api/paddle/tensor/search/masked_select_cn.rst index 52462854377085ebb39bb5f0c88fedb2ccbc6884..cecffda2c283dde127660a0a1b7083f64dbe102d 100644 --- a/doc/paddle/api/paddle/tensor/search/masked_select_cn.rst +++ b/doc/paddle/api/paddle/tensor/search/masked_select_cn.rst @@ -1,57 +1,43 @@ -.. _cn_api_fluid_layers_masked_select: +.. _cn_api_tensor_masked_select: masked_select ------------------------------- -.. py:function:: paddle.fluid.layers.masked_select(input, mask) +.. py:function:: paddle.masked_select(x, mask, name=None) -该OP将根据mask Tensor的真值选取输入Tensor元素，并返回一个一维Tensor -参数： - - **input** （Variable）- 输入Tensor，数据类型为int32, float32, float64。 - - **mask** （Variable）- mask Tensor， 数据类型为bool。 +该OP返回一个1-D 的Tensor, Tensor的值是根据 ``mask`` 对输入 ``x`` 进行选择的， ``mask`` 的数据类型是bool 。 -返回：根据mask选择后的tensor +参数： + - **x** (Tensor) - 输入Tensor, 数据类型为float32， float64，int32 或者int64。 + - **mask** (Tensor) - 用于索引的二进制掩码的Tensor，数据类型维bool。 + - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：返回一个根据 ``mask`` 选择的的Tensor -返回类型： Variable +抛出异常： + - ``TypeError``: - 如果 ``x`` 不是 Tensor 或者 ``x`` 是Tensor的时候的数据类型不是 float32, float64, int32, int64其中之一。 + - ``TypeError``: - 如果 ``mask`` 不是 Tensor 或者 ``mask`` 是Tensor的时候的数据类型不是 bool。 -**示例代码** +**代码示例**： -.. code-block:: python +.. code-block:: python - import paddle.fluid as fluid + import paddle import numpy as np - mask_shape = [4,1] - shape = [4,4] - data = np.random.random(mask_shape).astype("float32") - input_data = np.random.randint(5,size=shape).astype("float32") - mask_data = data > 0.5 - - # print(input_data) - # [[0.38972723 0.36218056 0.7892614 0.50122297] - # [0.14408113 0.85540855 0.30984417 0.7577004 ] - # [0.97263193 0.5248062 0.07655851 0.75549215] - # [0.26214206 0.32359877 0.6314582 0.2128865 ]] - - # print(mask_data) - # [[ True] - # [ True] - # [False] - # [ True]] - - input = fluid.data(name="input",shape=[4,4],dtype="float32") - mask = fluid.data(name="mask",shape=[4,1],dtype="bool") - result = fluid.layers.masked_select(input=input, mask=mask) - place = fluid.CPUPlace() - exe = fluid.Executor(place) - start = fluid.default_startup_program() - main = fluid.default_main_program() - exe.run(start) - masked_select_result= exe.run(main, feed={'input':input_data, 'mask':mask_data}, fetch_list=[result]) - # print(masked_select_result) - # [0.38972723 0.36218056 0.7892614 0.50122297 0.14408113 0.85540855 - # 0.30984417 0.7577004 0.26214206 0.32359877 0.6314582 0.2128865 ] - + + paddle.disable_static() + data = np.array([[1.0, 2.0, 3.0, 4.0], + [5.0, 6.0, 7.0, 8.0], + [9.0, 10.0, 11.0, 12.0]]).astype('float32') + + mask_data = np.array([[True, False, False, False], + [True, True, False, False], + [True, False, False, False]]).astype('bool') + x = paddle.to_tensor(data) + mask = paddle.to_tensor(mask_data) + out = paddle.masked_select(x, mask) + #[1.0 5.0 6.0 9.0] diff --git a/doc/paddle/api/paddle/tensor/search/sort_cn.rst b/doc/paddle/api/paddle/tensor/search/sort_cn.rst index f57b1e438b8bf9bcb7eb6544d5efcccb413e7a3b..dc791485e0327e588091e628b3efdb8e3b04fe00 100644 --- a/doc/paddle/api/paddle/tensor/search/sort_cn.rst +++ b/doc/paddle/api/paddle/tensor/search/sort_cn.rst @@ -9,7 +9,7 @@ sort :alias: paddle.sort,paddle.tensor.sort,paddle.tensor.search.sort -对输入变量沿给定轴进行排序，输出排序好的数据和相应的索引，其维度和输入相同。**默认升序排列，如果需要降序排列设置** ``descending=True`` 。 +对输入变量沿给定轴进行排序，输出排序好的数据，其维度和输入相同。默认升序排列，如果需要降序排列设置 ``descending=True`` 。 参数： @@ -18,9 +18,8 @@ sort - **descending** (bool，可选) - 指定算法排序的方向。如果设置为True，算法按照降序排序。如果设置为False或者不设置，按照升序排序。默认值为False。 - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -返回：一组已排序的输出（与 ``x`` 维度相同、数据类型相同）和索引（数据类型为int64）。 +返回：Tensor, 排序后的输出（与 ``x`` 维度相同、数据类型相同）。 -返回类型：tuple[Tensor] **代码示例**： @@ -41,28 +40,21 @@ sort out1 = paddle.sort(x=x, axis=-1) out2 = paddle.sort(x=x, axis=0) out3 = paddle.sort(x=x, axis=1) - print(out1[0].numpy()) + print(out1.numpy()) #[[[5. 5. 8. 9.] # [0. 0. 1. 7.] # [2. 4. 6. 9.]] # [[2. 2. 4. 5.] # [4. 7. 7. 9.] # [0. 1. 6. 7.]]] - print(out1[1].numpy()) - #[[[0 3 1 2] - # [0 1 2 3] - # [2 3 0 1]] - # [[1 3 2 0] - # [0 1 2 3] - # [2 0 3 1]]] - print(out2[0].numpy()) + print(out2.numpy()) #[[[5. 2. 4. 2.] # [0. 0. 1. 7.] # [1. 7. 0. 4.]] # [[5. 8. 9. 5.] # [4. 7. 7. 9.] # [6. 9. 2. 6.]]] - print(out3[0].numpy()) + print(out3.numpy()) #[[[0. 0. 1. 4.] # [5. 8. 2. 5.] # [6. 9. 9. 7.]] diff --git a/doc/paddle/api/paddle/tensor/search/topk_cn.rst b/doc/paddle/api/paddle/tensor/search/topk_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..47d73f11b02224ad073f1b5fe53fd9a85cddfe8b --- /dev/null +++ b/doc/paddle/api/paddle/tensor/search/topk_cn.rst @@ -0,0 +1,63 @@ +.. _cn_api_tensor_cn_topk: + +topk +------------------------------- + +.. py:function:: paddle.topk（x, k, axis=None, largest=True, sorted=True, name=None） + +该OP沿着可选的 ``axis`` 查找topk最大或者最小的结果和结果所在的索引信息。 +如果是一维Tensor，则直接返回topk查询的结果。如果是多维Tensor，则在指定的轴上查询topk的结果。 + +参数 +::::::::: + - **x** （Tensor） - 输入的多维 ``Tensor`` ，支持的数据类型：float32、float64、int32、int64。 + - **k** （int，Tensor） - 在指定的轴上进行top寻找的数量。 + - **axis** （int，可选） - 指定对输入Tensor进行运算的轴， ``axis`` 的有效范围是[-R, R），R是输入 ``x`` 的Rank， ``axis`` 为负时与 ``axis`` + R 等价。默认值为-1。 + - **largest** （bool，可选） - 指定算法排序的方向。如果设置为True，排序算法按照降序的算法排序，否则按照升序排序。默认值为True。 + - **sorted** （bool，可选） - 控制返回的结果是否按照有序返回，默认为True。在gpu上总是返回有序的结果。 + - **name** （str，可选） – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回 +::::::::: +tuple（Tensor）, 返回topk的结果和结果的索引信息。结果的数据类型和输入 ``x`` 一致。索引的数据类型是int64。 + +代码示例 +::::::::: + + +.. code-block:: python + + import numpy as np + import paddle + + paddle.disable_static() + + data_1 = np.array([1, 4, 5, 7]) + tensor_1 = paddle.to_tensor(data_1) + value_1, indices_1 = paddle.topk(tensor_1, k=1) + print(value_1.numpy()) + # [7] + print(indices_1.numpy()) + # [3] + data_2 = np.array([[1, 4, 5, 7], [2, 6, 2, 5]]) + tensor_2 = paddle.to_tensor(data_2) + value_2, indices_2 = paddle.topk(tensor_2, k=1) + print(value_2.numpy()) + # [[7] + # [6]] + print(indices_2.numpy()) + # [[3] + # [1]] + value_3, indices_3 = paddle.topk(tensor_2, k=1, axis=-1) + print(value_3.numpy()) + # [[7] + # [6]] + print(indices_3.numpy()) + # [[3] + # [1]] + value_4, indices_4 = paddle.topk(tensor_2, k=1, axis=0) + print(value_4.numpy()) + # [[2 6 5 7]] + print(indices_4.numpy()) + # [[1 1 0 0]] + diff --git a/doc/paddle/api/paddle/tensor/stat/numel_cn.rst b/doc/paddle/api/paddle/tensor/stat/numel_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..360dad0e10f2359bcc971d9a6fbfb60bb2e0a1e9 --- /dev/null +++ b/doc/paddle/api/paddle/tensor/stat/numel_cn.rst @@ -0,0 +1,26 @@ +.. _cn_api_tensor_numel: + +numel +------------------------------- + +.. py:function:: paddle.numel(x) + + +该OP返回一个长度为1并且元素值为输入 ``x`` 元素个数的Tensor。 + +参数： + - **x** (Tensor) - 输入Tensor，数据类型为int32，int64， float16, float32, float64, int32, int64 。 + +返回: 返回长度为1并且元素值为 ``x`` 元素个数的Tensor。 + + +**代码示例**： + +.. code-block:: python + + import paddle + + paddle.disable_static() + x = paddle.full(shape=[4, 5, 7], fill_value=0, dtype='int32') + numel = paddle.numel(x) # 140 + diff --git a/doc/paddle/api/paddle/tensor/stat/std_cn.rst b/doc/paddle/api/paddle/tensor/stat/std_cn.rst index 30aa83d07a730c336e7f1ca7c6df79a88dd93778..eb30280cc8b88e4ced5e54e1ad62ecda4af5f5d1 100644 --- a/doc/paddle/api/paddle/tensor/stat/std_cn.rst +++ b/doc/paddle/api/paddle/tensor/stat/std_cn.rst @@ -1,39 +1,37 @@ +.. _cn_api_tensor_cn_std: + std ------------------------------- -.. py:function:: paddle.std(input, axis=None, keepdim=False, unbiased=True, out=None, name=None) - -:alias_main: paddle.std -:alias: paddle.std,paddle.tensor.std,paddle.tensor.stat.std - - - -根据指定的axis计算input的标准差。 +.. py:function:: paddle.std(x, axis=None, unbiased=True, keepdim=False, name=None) -参数： - - **input** (Variable) - 数据类型为float32,float64。要计算标准差的输入。 - - **axis** (list|int, 可选) - 根据axis计算标准差。如果设为 `None`，计算 :attr:`input` 的所有元素的标准差并返回shape为[1]的单个结果。如果不是 `None`, 则设定的axis的值必须在 :math:`[-rank(input), rank(input))` 范围内。 如果 :math:`axis[i] < 0`, 则要计算的axis是 :math:`rank(input) + axis[i]`。 - - **keepdim** (bool, 可选) - 是否在输出中保留减小的维度。如 keep_dim 为False，输出张量的维度将比输入张量小， 为True时则维度相同。默认值：False。 - - **unbiased** (bool, 可选) - 是否使用无偏估计来计算标准差。使用 :math:`N` 来代表在axis上的维度，如果 unbiased 为True, 则在计算中使用 :math:`N - 1` 作为除数。为False时将使用 :math:`N` 作为除数。默认值：True。 - - **out** (Variable, 可选) - 如果out不是None, 则将标准差结果存储在out中。默认值：None。 - - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 +沿给定的轴 ``axis`` 计算 ``x`` 中元素的标准差。 +参数 +:::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。 + - axis (int|list|tuple, 可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是int、list(int)、tuple(int)。如果 ``axis`` 包含多个维度，则沿着 ``axis`` 中的所有轴进行计算。``axis`` 或者其中的元素值应该在范围[-D, D)内，D是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于0，则等价于 :math:`axis + D` 。如果 ``axis`` 是None，则对 ``x`` 的全部元素计算标准差。默认值为None。 + - unbiased (bool, 可选) - 是否使用无偏估计来计算标准差。使用 :math:`N` 来代表在 axis 上的维度，如果 ``unbiased`` 为True, 则在计算中使用 :math:`N - 1` 作为除数。为 False 时将使用 :math:`N` 作为除数。默认值为True。 + - keepdim (bool, 可选) - 是否在输出Tensor中保留减小的维度。如果 ``keepdim`` 为True，则输出Tensor和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为1)。否则，输出Tensor的形状会在 ``axis`` 上进行squeeze操作。默认值为False。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 -返回: 计算出来的标准差。 +返回 +:::::::::: + ``Tensor`` ，沿着 ``axis`` 进行标准差计算的结果，数据类型和 ``x`` 相同。 -返回类型: Variable（Tensor) ，数据类型和 :attr:`input` 相同。如果 :attr:`out = None`, 返回包含标准差的新Variable , 否则的话返回 :attr:`out` 的引用。 - -**代码示例** +代码示例 +:::::::::: .. code-block:: python - + import paddle - import paddle.fluid as fluid - # x is a Tensor variable with following elements: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # Each example is followed by the corresponding output tensor. - x = fluid.data(name='x', shape=[2, 4], dtype='float32') - paddle.std(x) # [0.28252685] - paddle.std(x, axis=[0]) # [0.0707107, 0.07071075, 0.07071064, 0.1414217] - paddle.std(x, axis=[-1]) # [0.30956957, 0.29439208] \ No newline at end of file + import numpy as np + + paddle.disable_static() + + x = np.array([[1.0, 2.0, 3.0], [1.0, 4.0, 5.0]]) + x = paddle.to_tensor(x) + out1 = paddle.std(x) + # [1.63299316] + out2 = paddle.std(x, axis=1) + # [1. 2.081666] diff --git a/doc/paddle/api/paddle/tensor/stat/var_cn.rst b/doc/paddle/api/paddle/tensor/stat/var_cn.rst index a0ee9e9b7edb2da0371c43bfc160a1ae33c46699..c44af2301a4ee0d192ec66738433014fced92eb2 100644 --- a/doc/paddle/api/paddle/tensor/stat/var_cn.rst +++ b/doc/paddle/api/paddle/tensor/stat/var_cn.rst @@ -1,38 +1,37 @@ +.. _cn_api_tensor_cn_var: + var ------------------------------- -.. py:function:: paddle.var(input, axis=None, keepdim=False, unbiased=True, out=None, name=None) - -:alias_main: paddle.var -:alias: paddle.var,paddle.tensor.var,paddle.tensor.stat.var - +.. py:function:: paddle.var(x, axis=None, unbiased=True, keepdim=False, name=None) +沿给定的轴 ``axis`` 计算 ``x`` 中元素的方差。 - 沿给定的轴 axis 计算输入变量所有元素的方差。 +参数 +:::::::::: + - x (Tensor) - 输入的Tensor，数据类型为：float32、float64。 + - axis (int|list|tuple, 可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是int、list(int)、tuple(int)。如果 ``axis`` 包含多个维度，则沿着 ``axis`` 中的所有轴进行计算。``axis`` 或者其中的元素值应该在范围[-D, D)内，D是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于0，则等价于 :math:`axis + D` 。如果 ``axis`` 是None，则对 ``x`` 的全部元素计算方差。默认值为None。 + - unbiased (bool, 可选) - 是否使用无偏估计来计算方差。使用 :math:`N` 来代表在 axis 上的维度，如果 ``unbiased`` 为True, 则在计算中使用 :math:`N - 1` 作为除数。为 False 时将使用 :math:`N` 作为除数。默认值为True。 + - keepdim (bool, 可选) - 是否在输出Tensor中保留减小的维度。如果 ``keepdim`` 为True，则输出Tensor和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为1)。否则，输出Tensor的形状会在 ``axis`` 上进行squeeze操作。默认值为False。 + - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 - 参数： - - **input** (Variable) - 要计算方差的输入变量，支持的数据类型为 float32 或 float64。 - - **axis** (list|int, 可选) - 给定的轴。如果设为 `None`，计算 :attr:`input` 的所有元素的方差并返回形状为 [1] 的单个结果。如果非 `None`, 则给定的 axis 的值必须在 :math:`[-rank(input), rank(input))` 范围内。 如果 :math:`axis[i] < 0`, 则实际的 axis 是 :math:`rank(input) + axis[i]`。 - - **keepdim** (bool, 可选) - 是否在输出中保留被规约的维度。如 keep_dim 为False，输出张量的维度将比输入张量小， 为True时则维度相同。默认值：False。 - - **unbiased** (bool, 可选) - 是否使用无偏估计来计算方差。使用 :math:`N` 来代表在 axis 上的维度，如果 unbiased 为True, 则在计算中使用 :math:`N - 1` 作为除数。为 False 时将使用 :math:`N` 作为除数。默认值：True。 - - **out** (Variable, 可选) - 如果out不是None, 则将方差结果存储在 out 中。默认值：None。 - - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 +返回 +:::::::::: + ``Tensor`` ，沿着 ``axis`` 进行方差计算的结果，数据类型和 ``x`` 相同。 - - 返回: 计算出来的方差。 +代码示例 +:::::::::: - 返回类型: Variable（Tensor) ，数据类型和 :attr:`input` 相同。如果 :attr:`out = None`, 返回包含方差的新 Variable , 否则返回 :attr:`out` 的引用。 +.. code-block:: python - **代码示例** + import paddle + import numpy as np + + paddle.disable_static() - .. code-block:: python - - import numpy as np - import paddle - import paddle.fluid.dygraph as dg - a = np.array([[1.0, 2.0], [3.0, 4.0]]).astype("float32") - with dg.guard(): - data = dg.to_variable(a) - variance = paddle.var(data, axis=[1]) - print(variance.numpy()) - # [0.5 0.5] + x = np.array([[1.0, 2.0, 3.0], [1.0, 4.0, 5.0]]) + x = paddle.to_tensor(x) + out1 = paddle.var(x) + # [2.66666667] + out2 = paddle.var(x, axis=1) + # [1. 4.33333333] diff --git a/doc/paddle/api/paddle/fluid/layers/BeamSearchDecoder_cn.rst b/doc/paddle/api/paddle/text/BeamSearchDecoder_cn.rst similarity index 87% rename from doc/paddle/api/paddle/fluid/layers/BeamSearchDecoder_cn.rst rename to doc/paddle/api/paddle/text/BeamSearchDecoder_cn.rst index 67e7312aaef57ff031e410031aecc73bc50c265f..d62d05ae86bda97df4fe06e328653df5251db4cd 100644 --- a/doc/paddle/api/paddle/fluid/layers/BeamSearchDecoder_cn.rst +++ b/doc/paddle/api/paddle/text/BeamSearchDecoder_cn.rst @@ -20,7 +20,7 @@ BeamSearchDecoder - **start_token** (int) - 起始标记id。 - **end_token** (int) - 结束标记id。 - **beam_size** (int) - 在beam search中使用的beam宽度。 - - **embedding_fn** (可选) - 处理选中的候选id的接口。通常，它是一个将词id转换为词嵌入的嵌入层，函数的返回值作为 :code:`cell.call` 接口的 :code:`input` 参数。如果 :code:`embedding_fn` 未提供，则必须在 :code:`cell.call` 中实现词嵌入转换。默认值None。 + - **embedding_fn** (可选) - 处理选中的候选id的接口。它通常是一个将词id转换为词嵌入的嵌入层，其返回值将作为 :code:`cell.call` 接口的 :code:`input` 参数。**注意** ，这里要使用 :ref:`cn_api_fluid_embedding` 而非 :ref:`cn_api_fluid_layers_embedding`，因为选中的id的形状是 :math:`[batch\_size, beam\_size]` ，如果使用后者则还需要在这里提供unsqueeze。如果 :code:`embedding_fn` 未提供，则必须在 :code:`cell.call` 中实现词嵌入转换。默认值None。 - **output_fn** (可选) - 处理cell输出的接口，在计算得分和选择候选标记id之前使用。默认值None。 **示例代码** @@ -123,7 +123,7 @@ BeamSearchDecoder 参数： - **initial_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。调用者提供的参数。 -返回：一个元组 :code:`(initial_inputs, initial_states, finished)`。:code:`initial_inputs` 是一个tensor，当 :code:`embedding_fn` 为None时，由 :code:`start_token` 填充，形状为 :math:`[batch\_size,beam\_size,1]` ；否则使用 :code:`embedding_fn(t)` 返回的值。:code:`initial_states` 是tensor变量的嵌套结构(命名元组，字段包括 :code:`cell_states，log_probs，finished，lengths`)，其中 :code:`log_probs，finished，lengths` 都含有一个tensor，形状为 :math:`[batch\_size, beam\_size]`，数据类型为float32，bool，int64。:code:`cell_states` 具有与输入参数 :code:`initial_cell_states` 相同结构的值，但形状扩展为 :math:`[batch\_size,beam\_size,...]`。 :code:`finished` 是一个布尔型tensor，由False填充，形状为 :math:`[batch\_size,beam\_size]`。 +返回：一个元组 :code:`(initial_inputs, initial_states, finished)`。:code:`initial_inputs` 是一个tensor，当 :code:`embedding_fn` 为None时，该tensor t的形状为 :math:`[batch\_size,beam\_size]` ，值为 :code:`start_token` ；否则使用 :code:`embedding_fn(t)` 返回的值。:code:`initial_states` 是tensor变量的嵌套结构(命名元组，字段包括 :code:`cell_states，log_probs，finished，lengths`)，其中 :code:`log_probs，finished，lengths` 都含有一个tensor，形状为 :math:`[batch\_size, beam\_size]`，数据类型为float32，bool，int64。:code:`cell_states` 具有与输入参数 :code:`initial_cell_states` 相同结构的值，但形状扩展为 :math:`[batch\_size,beam\_size,...]`。 :code:`finished` 是一个布尔型tensor，由False填充，形状为 :math:`[batch\_size,beam\_size]`。 返回类型：tuple @@ -135,7 +135,7 @@ BeamSearchDecoder - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 - **logits** (Variable) - 形状为 :math:`[batch\_size,beam\_size,vocab\_size]` 的tensor，表示当前时间步的logits。其数据类型为float32。 - **next_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。它的结构，形状和数据类型与 :code:`initialize()` 的返回值 :code:`initial_states` 中的 :code:`cell_states` 相同。它代表该cell的下一个状态。 - - **beam_state** (Variable) - tensor变量的结构。在第一个解码步骤与 :code:`initialize()` 返回的 :code:`initial_states` 同，其他步骤与 :code:`initialize()` 返回的 :code:`beam_search_state` 相同。 + - **beam_state** (Variable) - tensor变量的结构。在第一个解码步骤与 :code:`initialize()` 返回的 :code:`initial_states` 同，其他步骤与 :code:`step()` 返回的 :code:`beam_search_state` 相同。 返回：一个元组 :code:`(beam_search_output, beam_search_state)`。:code:`beam_search_output` 是tensor变量的命名元组，字段为 :code:`scores，predicted_ids parent_ids`。其中 :code:`scores，predicted_ids，parent_ids` 都含有一个tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为float32 ，int64，int64。:code:`beam_search_state` 具有与输入参数 :code:`beam_state` 相同的结构，形状和数据类型。 @@ -146,9 +146,9 @@ BeamSearchDecoder 执行beam search解码步骤，该步骤使用 :code:`cell` 来计算概率，然后执行beam search步骤以计算得分并选择候选标记ID。 参数： - - **time** (Variable) - 调用者提供的形状为[1]的int64tensor，表示当前解码的时间步长。 + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。。 - **inputs** (Variable) - tensor变量。在第一个解码时间步时与由 :code:`initialize()` 返回的 :code:`initial_inputs` 相同，其他时间步与由 :code:`step()` 返回的 :code:`next_inputs` 相同。 - - **States** (Variable) - tensor变量的结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`beam_search_state` 相同。 + - **states** (Variable) - tensor变量的结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`beam_search_state` 相同。 - **kwargs** - 附加的关键字参数，由调用者提供。 返回：一个元组 :code:`(beam_search_output，beam_search_state，next_inputs，finish)` 。:code:`beam_search_state` 和参数 :code:`states` 具有相同的结构，形状和数据类型。 :code:`next_inputs` 与输入参数 :code:`inputs` 具有相同的结构，形状和数据类型。 :code:`beam_search_output` 是tensor变量的命名元组(字段包括 :code:`scores，predicted_ids，parent_ids` )，其中 :code:`scores，predicted_ids，parent_ids` 都含有一个tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为float32 ，int64，int64。:code:`finished` 是一个bool类型的tensor，形状为 :math:`[batch\_size,beam\_size]`。 @@ -167,12 +167,3 @@ BeamSearchDecoder 返回：一个元组 :code:`(predicted_ids, final_states)`。:code:`predicted_ids` 是一个tensor，形状为 :math:`[time\_step，batch\_size,beam\_size]`，数据类型为int64。:code:`final_states` 与输入参数 :code:`final_states` 相同。 返回类型：tuple - -.. py:method:: output_dtype() - -用于beam search输出的数据类型的嵌套结构。它是一个命名元组，字段包括 :code:`scores, predicted_ids, parent_ids`。 - -参数：无。 - -返回：用于beam search输出的数据类型的命名元组。 - diff --git a/doc/paddle/api/paddle/text/RNNCell_cn.rst b/doc/paddle/api/paddle/text/RNNCell_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..1368e2ac33f57a483ced44c49ccf65aa83671f7a --- /dev/null +++ b/doc/paddle/api/paddle/text/RNNCell_cn.rst @@ -0,0 +1,50 @@ +.. _cn_api_fluid_layers_RNNCell: + +RNNCell +------------------------------- + + + +.. py:class:: paddle.fluid.layers.RNNCell(name=None) + +:api_attr: 声明式编程模式（静态图) + + +RNNCell是抽象的基类，代表将输入和状态映射到输出和新状态的计算，主要用于RNN。 + +.. py:method:: call(inputs, states, **kwargs) + +每个cell都必须实现此接口，将（输入和状态）映射到（输出和新状态）。为了更灵活，输入和状态都可以是单个tensor变量或嵌套结构的tensor变量（列表 | 元组 | 命名元组 | 字典）。 + +参数： + - **inputs** - 输入，为单个tensor变量或tensor变量组成的嵌套结构。 + - **states** - 状态，单个tensor变量或tensor变量组成的嵌套结构。 + - **kwargs** - 附加的关键字参数，由调用者提供。 +         +返回：包含输出和新状态的二元组 :code:`(outputs，new_states)` 。输出和新状态都可以是嵌套的tensor变量。新状态必须具有与状态相同的结构。 + +返回类型：tuple + +.. py:method:: get_initial_states(batch_ref, shape=None, dtype=None, init_value=0, batch_dim_idx=0) + +该接口根据提供的形状，数据类型和初始值来初始化状态。 + +参数： + - **batch_ref** - 单个tensor变量或tensor组成的嵌套结构。 tensor的第一维将用作初始化状态的batch大小。 + - **shape** - 单个形状或形状组成的嵌套结构，单个形状是整数的列表或元组。 如果形状的第一维不是batch大小，则自动插入-1作为batch大小。 如果该项为None，将使用属性 :code:`state_shape`。默认值为None。 + - **dtype** - 单个数据类型或由数据类型组成的嵌套结构。该结构必须与shape的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 如果是None并且属性 :code:`cell.state_shape` 不可用，则float32将用作数据类型。 默认值为None。 + - **init_value** - 用于初始化状态的浮点值。 + - **batch_dim_idx** - 用于指示 :code:`batch_ref` 中batch所在维度的int值，默认值为0。 + +返回：和shape具有相同结构的tensor变量，代表初始状态。 + +返回类型：Variable + +.. py:method:: state_shape() + +抽象方法（属性），该接口用于初始化cell的状态。 单个形状或由形状组成的嵌套结构，单个形状可以是整数的列表或元组(如果形状的第一维不是batch大小，则自动插入-1作为batch大小)。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`shape` 参数的时候，不用实现该方法。 + + +.. py:method:: state_dtype() + +抽象方法（属性），该接口用于初始化cell的状态。 单个数据类型或由数据类型组成的嵌套结构，该结构必须与 :code:`shape` 的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`dtype` 参数的时候，不用实现该方法。 diff --git a/doc/paddle/api/paddle/vision/flip_cn.rst b/doc/paddle/api/paddle/vision/flip_cn.rst new file mode 100644 index 0000000000000000000000000000000000000000..d8f1f7efd1b9a2c74d9902ae4c0c58d6dafa6f22 --- /dev/null +++ b/doc/paddle/api/paddle/vision/flip_cn.rst @@ -0,0 +1,43 @@ +.. _cn_api_tensor_flip: + +flip +------------------------------- + +.. py:function:: paddle.flip(x, axis, name=None): + +:alias_main: paddle.flip +:alias: paddle.flip, paddle.tensor.flip, paddle.tensor.manipulation.flip + + + +该OP沿指定轴反转n维tensor. + +参数： + - **x** (Variable) - 输入张量。维度为多维，数据类型为bool, int32, int64, float32或float64。 + - **axis** (list) - 需要翻转的轴。当 ``axis[i] < 0`` 时，实际的计算维度为 ndim(x) + axis[i]，其中i为axis的索引。 + - **name** (str|None) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。默认值为None。 + +返回：在指定axis上翻转后的张量，与输入x数据类型相同。 + +返回类型：Variable，与输入x数据类型相同。 + +抛出异常： + - ``TypeError`` - 当输出 ``out`` 和输入 ``x`` 数据类型不一致时候。 + - ``ValueError`` - 当参数 ``axis`` 不合法时。 + +**代码示例1**： + +.. code-block:: python + + import paddle + import numpy as np + + paddle.enable_imperative() + + image_shape=(3, 2, 2) + x = np.arange(image_shape[0] * image_shape[1] * image_shape[2]).reshape(image_shape) + x = x.astype('float32') + img = paddle.imperative.to_variable(x) + out = paddle.flip(img, [0,1]) + print(out) # [[[10,11][8, 9]],[[6, 7],[4, 5]] [[2, 3],[0, 1]]] +