From aa20a2407b803a6b5dbf4b054346367004d6d7ef Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Wed, 21 Sep 2022 00:11:37 +0800 Subject: [PATCH 1/8] add paddle.geometric --- .../message_passing/send_u_recv_cn.rst | 8 +++ .../message_passing/send_ue_recv_cn.rst | 8 +++ .../geometric/message_passing/send_uv_cn.rst | 8 +++ .../api/paddle/geometric/reindex_graph_cn.rst | 38 +++++++++++++ .../geometric/reindex_heter_graph_cn.rst | 39 ++++++++++++++ .../paddle/geometric/sample_neighbors_cn.rst | 31 +++++++++++ .../sampling/sample_neighbors_cn.rst | 8 +++ docs/api/paddle/geometric/segment_max_cn.rst | 34 ++++++++++++ docs/api/paddle/geometric/segment_mean_cn.rst | 34 ++++++++++++ docs/api/paddle/geometric/segment_min_cn.rst | 34 ++++++++++++ docs/api/paddle/geometric/segment_sum_cn.rst | 36 +++++++++++++ docs/api/paddle/geometric/send_u_recv_cn.rst | 47 ++++++++++++++++ docs/api/paddle/geometric/send_ue_recv_cn.rst | 53 +++++++++++++++++++ docs/api/paddle/geometric/send_uv_cn.rst | 44 +++++++++++++++ 14 files changed, 422 insertions(+) create mode 100644 docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst create mode 100644 docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst create mode 100644 docs/api/paddle/geometric/message_passing/send_uv_cn.rst create mode 100644 docs/api/paddle/geometric/reindex_graph_cn.rst create mode 100644 docs/api/paddle/geometric/reindex_heter_graph_cn.rst create mode 100644 docs/api/paddle/geometric/sample_neighbors_cn.rst create mode 100644 docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst create mode 100644 docs/api/paddle/geometric/segment_max_cn.rst create mode 100644 docs/api/paddle/geometric/segment_mean_cn.rst create mode 100644 docs/api/paddle/geometric/segment_min_cn.rst create mode 100644 docs/api/paddle/geometric/segment_sum_cn.rst create mode 100644 docs/api/paddle/geometric/send_u_recv_cn.rst create mode 100644 docs/api/paddle/geometric/send_ue_recv_cn.rst create mode 100644 docs/api/paddle/geometric/send_uv_cn.rst diff --git a/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst b/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst new file mode 100644 index 00000000000..5104e16acb3 --- /dev/null +++ b/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst @@ -0,0 +1,8 @@ +.. _cn_api_geometric_message_passing_send_u_recv: + +send_u_recv +------------------------------- + +.. py:function:: paddle.geometric.message_passing.send_u_recv(x, src_index, dst_index, reduce_op="sum", out_size=None, name=None) + +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_paddle_geometric_send_u_recv` 功能一致。 diff --git a/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst b/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst new file mode 100644 index 00000000000..c40bc7c6fbc --- /dev/null +++ b/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst @@ -0,0 +1,8 @@ +.. _cn_api_geometric_message_passing_send_ue_recv: + +send_ue_recv +------------------------------- + +.. py:function:: paddle.geometric.message_passing.send_ue_recv(x, y, src_index, dst_index, message_op="add", reduce_op="sum", out_size=None, name=None) + +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_paddle_geometric_send_ue_recv` 功能一致。 diff --git a/docs/api/paddle/geometric/message_passing/send_uv_cn.rst b/docs/api/paddle/geometric/message_passing/send_uv_cn.rst new file mode 100644 index 00000000000..ff66e604495 --- /dev/null +++ b/docs/api/paddle/geometric/message_passing/send_uv_cn.rst @@ -0,0 +1,8 @@ +.. _cn_api_geometric_message_passing_send_uv: + +send_ue_recv +------------------------------- + +.. py:function:: paddle.geometric.message_passing.send_uv(x, y, src_index, dst_index, message_op="add", name=None) + +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_paddle_geometric_send_uv` 功能一致。 diff --git a/docs/api/paddle/geometric/reindex_graph_cn.rst b/docs/api/paddle/geometric/reindex_graph_cn.rst new file mode 100644 index 00000000000..5aed51fdb1d --- /dev/null +++ b/docs/api/paddle/geometric/reindex_graph_cn.rst @@ -0,0 +1,38 @@ +.. _cn_api_geometric_reindex_graph: + +reindex_graph +------------------------------- + +.. py:function:: paddle.geometric.reindex_graph(x, neighbors, count, value_buffer=None, index_buffer=None, name=None) + +主要应用于图学习领域，需要与图采样相关的 API 配合使用，主要处理同构图场景。其主要目的是对输入的中心节点信息和邻居信息进行从 0 开始的重新编号，以方便后续的图模型子图训练。 + +**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从0进行编号。 + +以输入 x = [0, 1, 2] 作为例子解释。假设我们有邻居 neighbors = [8, 9, 0, 4, 7, 6, 7]，以及邻居数量 count = [2, 3, 2]。 +则可以得知节点 0 的邻居为 [8, 9]，节点 1 的邻居为 [0, 4, 7]，节点 2 的邻居为 [6, 7]。经过此 API 计算后，共计会返回三个结果： + 1. reindex_src: [3, 4, 0, 5, 6, 7, 6] + 2. reindex_dst: [0, 0, 1, 1, 1, 2, 2] + 3. out_nodes: [0, 1, 2, 8, 9, 4, 7, 6] +可以看到 ``reindex_src`` 和 ``reindex_dst`` 中的值实际上是各个节点在 ``out_nodes`` 中对应的下标索引。 + +参数 +::::::::: + - x (Tensor) - 输入的中心节点原始编号，数据类型为：int32、int64。 + - neighbors (Tensor) - 中心节点的邻居节点编号，数据类型为：int32、int64。 + - count (Tensor) - 中心节点各自的邻居数目，数据类型为：int32。 + - value_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。 + - index_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。如果需要使用加速重编号过程，则 ``value_buffer`` 和 ``index_buffer`` 均不可为空。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + - reindex_src (Tensor) - 重编号后的边对应的源节点信息。 + - reindex_dst (Tensor) - 重编号后的边对应的目标节点信息。 + - out_nodes (Tensor) - 返回去重后的输入中心节点信息和邻居信息，且为原始编号。注意，我们将输入的中心节点编号信息放置于前面，而邻居节点放置于后面。 + + +代码示例 +:::::::::: + +COPY-FROM: paddle.geometric.reindex_graph diff --git a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst new file mode 100644 index 00000000000..dfbcc98c325 --- /dev/null +++ b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst @@ -0,0 +1,39 @@ +.. _cn_api_geometric_reindex_heter_graph: + +reindex_heter_graph +------------------------------- + +.. py:function:: paddle.geometric.reindex_heter_graph(x, neighbors, count, value_buffer=None, index_buffer=None, name=None) + +主要应用于图学习领域，需要与图采样相关的 API 配合使用，主要处理异构图场景。其主要目的是对输入的中心节点信息和邻居信息进行从 0 开始的重新编号，以方便后续的图模型子图训练。 + +**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从0进行编号。 + +以输入 x = [0, 1, 2] 作为例子解释。对于异构图 A ，假设我们有邻居 neighbors = [8, 9, 0, 4, 7, 6, 7]，以及邻居数量 count = [2, 3, 2]； +则可以得知节点 0 的邻居为 [8, 9]，节点 1 的邻居为 [0, 4, 7]，节点 2 的邻居为 [6, 7]。对于异构图 B，假设有邻居 neighbors = [0, 2, 3, 5, 1]， +以及邻居数量 count = [1, 3, 1]，则可以得知节点 0 的邻居为 [0]，节点 1 的邻居为 [2, 3, 5]。经过此 API 计算后，共计会返回三个结果： + 1. reindex_src: [3, 4, 0, 5, 6, 7, 6, 0, 2, 8, 9, 1] + 2. reindex_dst: [0, 0, 1, 1, 1, 2, 2, 0, 1, 1, 1, 2] + 3. out_nodes: [0, 1, 2, 8, 9, 4, 7, 6, 3, 5] +可以看到 ``reindex_src`` 和 ``reindex_dst`` 中的值实际上是各个节点在 ``out_nodes`` 中对应的下标索引。 + +参数 +::::::::: + - x (Tensor) - 输入的中心节点原始编号，数据类型为：int32、int64。 + - neighbors (list | tuple) - 中心节点对应到各个异构图中的邻居节点编号，数据类型为：int32、int64。 + - count (list | tuple) - 中心节点对应到各个异构图中的邻居数目，数据类型为：int32。 + - value_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。 + - index_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。如果需要使用加速重编号过程，则 ``value_buffer`` 和 ``index_buffer`` 均不可为空。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + - reindex_src (Tensor) - 重编号后的边对应的源节点信息。 + - reindex_dst (Tensor) - 重编号后的边对应的目标节点信息。 + - out_nodes (Tensor) - 返回去重后的输入中心节点信息和邻居信息，且为原始编号。注意，我们将输入的中心节点编号信息放置于前面，而邻居节点放置于后面。 + + +代码示例 +:::::::::: + +COPY-FROM: paddle.geometric.reindex_heter_graph diff --git a/docs/api/paddle/geometric/sample_neighbors_cn.rst b/docs/api/paddle/geometric/sample_neighbors_cn.rst new file mode 100644 index 00000000000..d4d3add0083 --- /dev/null +++ b/docs/api/paddle/geometric/sample_neighbors_cn.rst @@ -0,0 +1,31 @@ +.. _cn_api_geometric_sample_neighbors: + +sample_neighbors +------------------------------- + +.. py:function:: paddle.geometric.sample_neighbors(row, colptr, input_nodes, sample_size=-1, eids=None, return_eids=False, perm_buffer=None, name=None) + +主要应用于图学习领域，主要目的是提供高性能图邻居采样方法。通过输入图的 CSC（Compressed Sparse Column，压缩列信息），分别对应 ``row`` 和 ``colptr``，从而将图转换为适用于邻居采样的格式，再输入需要进行采样的中心节点 ``input_nodes``，以及采样的邻居个数 ``sample_size``，从而可以获得对应中心节点采样后的邻居。另外，在 GPU 版本提供了 Fisher-yates 高性能图采样方法。 + +参数 +::::::::: + - row (Tensor) - 输入原始图的 CSC 格式的行信息，数据类型为：int32、int64，形状为[num_edges, 1] 或 [num_edges]。 + - colptr (Tensor) - 输入原始图的 CSC 格式的压缩列信息，数据类型应当与 ``row`` 一致，形状为[num_nodes + 1, 1]或 [num_nodes + 1]。 + - input_nodes (Tensor) - 需进行邻居采样的中心节点信息，数据类型应当与 ``row`` 一致。 + - sample_size (int) - 采样邻居个数。默认值为-1，表示采样输入中心节点的所有邻居。 + - eids (Tensor，可选) - 输入原始图在 CSC 格式下的边编号信息。如果 ``return_eids`` 为 True，则不能为空。数据类型应当与 ``row`` 一致。默认为 None，表示不需要返回边编号信息。 + - return_eids (bool) - 是否返回采样后对应的原始边编号信息，默认为 False。 + - perm_buffer (Tensor，可选) - Fisher-yates 采样方法需要用到的缓存 Tensor。如果需使用高性能图采样方法，则不能为空。数据类型应当与 ``row`` 一致，形状为[num_edges]，填充内容为 0 至 num_edges 的顺序递增序列。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + - out_neighbors (Tensor) - 返回采样后的邻居节点。 + - out_count (Tensor) - 返回中心节点各自对应的采样邻居数目，形状应该与 ``input_nodes`` 一致。 + - out_eids (Tensor) - 如果 ``return_eids`` 为 True，则会返回采样边对应的编号信息，否则不返回。 + + +代码示例 +:::::::::: + +COPY-FROM: paddle.geometric.sample_neighbors diff --git a/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst b/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst new file mode 100644 index 00000000000..d15ae420775 --- /dev/null +++ b/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst @@ -0,0 +1,8 @@ +.. _cn_api_geometric_sampling_sample_neighbors: + +sample_neighbors +------------------------------- + +.. py:function:: paddle.geometric.sampling.sample_neighbors(row, colptr, input_nodes, sample_size=-1, eids=None, return_eids=False, perm_buffer=None, name=None) + +主要应用于图学习领域，主要目的是提供高性能图邻居采样方法，与 :ref:`cn_api_paddle_geometric_sample_neighbors` 功能一致。 diff --git a/docs/api/paddle/geometric/segment_max_cn.rst b/docs/api/paddle/geometric/segment_max_cn.rst new file mode 100644 index 00000000000..1484728b781 --- /dev/null +++ b/docs/api/paddle/geometric/segment_max_cn.rst @@ -0,0 +1,34 @@ +.. _cn_api_geometric_segment_max: + +segment_max +------------------------------- + +.. py:function:: paddle.geometric.segment_max(data, segment_ids, name=None) + + +分段求最大值函数。 + +此运算符，将 ``segment_ids`` 中相同索引对应的 ``data`` 的元素，进行求最大值操作。其中 ``segment_ids`` 是一个单调非减序列。 +具体而言，该算子计算一个 Tensor ``out``，使得 + +.. math:: + + out_i = \max_{j \in \{segment\_ids_j == i \} } data_{j} + +其中求最大值的索引 ``j``，是符合 ``segment_ids[j] == i`` 的所有 ``j`` 。 + + +参数 +::::::::: + - **data** (Tensor) - 张量，数据类型为 float32、float64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + Tensor，分段求最大值的结果。空的 segment_id 对应的默认值为 0。 + +代码示例 +::::::::: + +COPY-FROM: paddle.geometric.segment_max diff --git a/docs/api/paddle/geometric/segment_mean_cn.rst b/docs/api/paddle/geometric/segment_mean_cn.rst new file mode 100644 index 00000000000..2df40273c24 --- /dev/null +++ b/docs/api/paddle/geometric/segment_mean_cn.rst @@ -0,0 +1,34 @@ +.. _cn_api_geometric_segment_mean: + +segment_mean +------------------------------- + +.. py:function:: paddle.geometric.segment_mean((data, segment_ids, name=None) + + +分段求均值函数。 + +此运算符，将 ``segment_ids`` 中相同索引对应的 ``data`` 的元素，进行求均值操作。其中 ``segment_ids`` 是一个单调非减序列。 +具体而言，该算子计算一个 Tensor ``out``，使得 + +.. math:: + + out_i = \mathop{mean}_{j \in \{segment\_ids_j == i \} } data_{j} + +其中求均值的索引 ``j``，是符合 ``segment_ids[j] == i`` 的所有 ``j`` 。 + + +参数 +::::::::: + - **data** (Tensor) - 张量，数据类型为 float32、float64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + Tensor，分段求均值的结果。空的 segment_id 对应的默认值为 0。 + +代码示例 +::::::::: + +COPY-FROM: paddle.geometric.segment_mean diff --git a/docs/api/paddle/geometric/segment_min_cn.rst b/docs/api/paddle/geometric/segment_min_cn.rst new file mode 100644 index 00000000000..9bbc0d82fa9 --- /dev/null +++ b/docs/api/paddle/geometric/segment_min_cn.rst @@ -0,0 +1,34 @@ +.. _cn_api_geometric_segment_min: + +segment_min +------------------------------- + +.. py:function:: paddle.geometric.segment_min((data, segment_ids, name=None) + + +分段求最小值函数。 + +此运算符，将 ``segment_ids`` 中相同索引对应的 ``data`` 的元素，进行求最小值操作。其中 ``segment_ids`` 是一个单调非减序列。 +具体而言，该算子计算一个 Tensor ``out``，使得 + +.. math:: + + out_i = \min_{j \in \{segment\_ids_j == i \} } data_{j} + +其中求最小值的索引 ``j``，是符合 ``segment_ids[j] == i`` 的所有 ``j`` 。 + + +参数 +::::::::: + - **data** (Tensor) - 张量，数据类型为 float32、float64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + Tensor，分段求最小值的结果。空的 segment_id 对应的默认值为 0。 + +代码示例 +::::::::: + +COPY-FROM: paddle.geometric.segment_min diff --git a/docs/api/paddle/geometric/segment_sum_cn.rst b/docs/api/paddle/geometric/segment_sum_cn.rst new file mode 100644 index 00000000000..a7f4ba7d65c --- /dev/null +++ b/docs/api/paddle/geometric/segment_sum_cn.rst @@ -0,0 +1,36 @@ +.. _cn_api_geometric_segment_sum: + +segment_sum +------------------------------- + +.. py:function:: paddle.geometric.segment_sum(data, segment_ids, name=None) + + +分段求和函数。 + +此运算符，将 ``segment_ids`` 中相同索引对应的 ``data`` 的元素，进行求和操作。其中 ``segment_ids`` 是一个单调非减序列。 +具体而言，该算子计算一个 Tensor ``out``，使得 + +.. math:: + + out_i = \sum_{j \in \{segment\_ids_j == i \} } data_{j} + +其中求和的索引 ``j``，是符合 ``segment_ids[j] == i`` 的所有 ``j`` 。 + + +参数 +::::::::: + + - **data** (Tensor) - 张量，数据类型为 float32、float64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: + + Tensor，分段求和的结果。空的 segment_id 对应的默认值为 0。 + +代码示例 +::::::::: + +COPY-FROM: paddle.geometric.segment_sum diff --git a/docs/api/paddle/geometric/send_u_recv_cn.rst b/docs/api/paddle/geometric/send_u_recv_cn.rst new file mode 100644 index 00000000000..f0b909da06b --- /dev/null +++ b/docs/api/paddle/geometric/send_u_recv_cn.rst @@ -0,0 +1,47 @@ +.. _cn_api_geometric_send_u_recv: + +send_u_recv +------------------------------- + +.. py:function:: paddle.geometric.send_u_recv(x, src_index, dst_index, reduce_op="sum", out_size=None, name=None) + +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗。其中，``x`` 作为输入的节点特征 Tensor，首先利用 ``src_index`` 作为索引来 gather 出在 ``x`` 中相应位置的数据，随后再将 gather 出的结果利用 ``dst_index`` 来更新到对应的输出结果中，其中 ``reduce_op`` 表示不同的更新方式，包括 sum、mean、max、min 共计 4 种处理模式。另外，提供了 ``out_size`` 参数，用于设置实际输出的形状，有利于减少实际显存占用。 + +.. code-block:: text + + X = [[0, 2, 3], + [1, 4, 5], + [2, 6, 7]] + + src_index = [0, 1, 2, 0] + + dst_index = [1, 2, 1, 0] + + reduce_op = "sum" + + out_size = None + + Then: + + Out = [[0, 2, 3], + [2, 8, 10], + [1, 4, 5]] + +参数 +::::::::: + - x (Tensor) - 输入的节点特征 Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - src_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。 + - dst_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 + - reduce_op (str) - 不同更新方式，包括 sum、mean、max、min。默认值为 sum。 + - out_size (int64 | Tensor | None) - 可以通过根据实际需求设置 ``out_size`` 来改变实际输出形状。默认值为 None，表示这个参数将不会被使用。注意，``out_size`` 的值必须等于或大于 ``max(dst_index) + 1`` 。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +``Tensor`` ，维度和数据类型都与 ``x`` 相同，存储运算后的结果。如果 ``out_size`` 参数正确设置了，则输出结果的第 0 维大小是 ``out_size`` ，其余维度大小与 ``x`` 相同。 + + +代码示例 +:::::::::: + +COPY-FROM: paddle.geometric.send_u_recv diff --git a/docs/api/paddle/geometric/send_ue_recv_cn.rst b/docs/api/paddle/geometric/send_ue_recv_cn.rst new file mode 100644 index 00000000000..cf01a5c120d --- /dev/null +++ b/docs/api/paddle/geometric/send_ue_recv_cn.rst @@ -0,0 +1,53 @@ +.. _cn_api_geometric_send_ue_recv: + +send_ue_recv +------------------------------- + +.. py:function:: paddle.geometric.send_ue_recv(x, y, src_index, dst_index, message_op="add", reduce_op="sum", out_size=None, name=None) + +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗。其中，``x`` 作为输入节点特征 Tensor，首先利用 ``src_index`` 作为索引来 gather 出在 ``x`` 中相应位置的数据，接着与边特征 Tensor ``e`` 进行计算，计算方式包括 add、sub、mul、div。随后再将计算的结果利用 ``dst_index`` 来更新到对应的输出结果中，其中 ``message_op`` 表示输入 ``x`` 和 ``e`` 之间的计算方式， ``reduce_op`` 表示不同的结果更新方式，包括 sum、mean、max、min 共计 4 种处理模式。另外，提供了 ``out_size`` 参数，用于设置实际输出的形状，有利于减少实际显存占用。 + +.. code-block:: text + + x = [[0, 2, 3], + [1, 4, 5], + [2, 6, 7]] + + y = [1, 1, 1] + + src_index = [0, 1, 2, 0] + + dst_index = [1, 2, 1, 0] + + message_op = "add" + + reduce_op = "sum" + + out_size = None + + Then: + + Out = [[1, 3, 4], + [4, 10, 12], + [2, 5, 6]] + +参数 +::::::::: + - x (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - y (Tensor) - 输入的边特征 Tensor，数据类型为：float32、float64、int32、int64。数据类型需与 ``x`` 相同。另外，我们在 GPU 计算中支持 float16。 + - src_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。 + - dst_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 + - message_op (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 + - reduce_op (str) - 不同更新方式，包括 sum、mean、max、min。默认值为 sum。 + - out_size (int64 | Tensor | None) - 可以通过根据实际需求设置 ``out_size`` 来改变实际输出形状。默认值为 None，表示这个参数将不会被使用。注意，``out_size`` 的值必须等于或大于 ``max(dst_index) + 1`` 。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +``Tensor`` ，维度和数据类型都与 ``x`` 相同，存储运算后的结果。如果 ``out_size`` 参数正确设置了，则输出结果的第 0 维大小是 ``out_size`` ，其余维度大小与 ``x`` 相同。 + + +代码示例 +:::::::::: + +COPY-FROM: paddle.geometric.send_ue_recv diff --git a/docs/api/paddle/geometric/send_uv_cn.rst b/docs/api/paddle/geometric/send_uv_cn.rst new file mode 100644 index 00000000000..f4c9540e490 --- /dev/null +++ b/docs/api/paddle/geometric/send_uv_cn.rst @@ -0,0 +1,44 @@ +.. _cn_api_geometric_send_uv: + +send_ue_recv +------------------------------- + +.. py:function:: paddle.geometric.send_uv(x, y, src_index, dst_index, message_op="add", name=None) + +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗。其中，``x`` 作为输入的节点特征 Tensor，首先利用 ``src_index`` 作为索引来 gather 出在 ``x`` 中相应位置的数据，接着利用 ``dst_index`` gather出 ``y`` 中相应位置的数据，再通过 ``message_op`` 确认计算方式，最终返回。其中，``message_op`` 包括另外 add、sub、mul、div共计四种计算方式。 + +.. code-block:: text + + x = [[0, 2, 3], + [1, 4, 5], + [2, 6, 7]] + + src_index = [0, 1, 2, 0] + + dst_index = [1, 2, 1, 0] + + message_op = "add" + + Then: + + Out = [[0, 2, 3], + [2, 8, 10], + [1, 4, 5]] + +参数 +::::::::: + - x (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - src_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。 + - dst_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 + - message_op (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +``Tensor`` ，输出更新后的边特征。 + + +代码示例 +:::::::::: + +COPY-FROM: paddle.geometric.send_uv From fbc91f447798dc90439a955867476e976c43cebd Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Wed, 21 Sep 2022 00:27:15 +0800 Subject: [PATCH 2/8] fix bug --- docs/api/paddle/geometric/message_passing/send_uv_cn.rst | 2 +- docs/api/paddle/geometric/segment_mean_cn.rst | 2 +- docs/api/paddle/geometric/segment_min_cn.rst | 2 +- docs/api/paddle/geometric/send_uv_cn.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/paddle/geometric/message_passing/send_uv_cn.rst b/docs/api/paddle/geometric/message_passing/send_uv_cn.rst index ff66e604495..1242705158b 100644 --- a/docs/api/paddle/geometric/message_passing/send_uv_cn.rst +++ b/docs/api/paddle/geometric/message_passing/send_uv_cn.rst @@ -1,6 +1,6 @@ .. _cn_api_geometric_message_passing_send_uv: -send_ue_recv +send_uv ------------------------------- .. py:function:: paddle.geometric.message_passing.send_uv(x, y, src_index, dst_index, message_op="add", name=None) diff --git a/docs/api/paddle/geometric/segment_mean_cn.rst b/docs/api/paddle/geometric/segment_mean_cn.rst index 2df40273c24..4b97673ddea 100644 --- a/docs/api/paddle/geometric/segment_mean_cn.rst +++ b/docs/api/paddle/geometric/segment_mean_cn.rst @@ -3,7 +3,7 @@ segment_mean ------------------------------- -.. py:function:: paddle.geometric.segment_mean((data, segment_ids, name=None) +.. py:function:: paddle.geometric.segment_mean(data, segment_ids, name=None) 分段求均值函数。 diff --git a/docs/api/paddle/geometric/segment_min_cn.rst b/docs/api/paddle/geometric/segment_min_cn.rst index 9bbc0d82fa9..7dfd854d2f4 100644 --- a/docs/api/paddle/geometric/segment_min_cn.rst +++ b/docs/api/paddle/geometric/segment_min_cn.rst @@ -3,7 +3,7 @@ segment_min ------------------------------- -.. py:function:: paddle.geometric.segment_min((data, segment_ids, name=None) +.. py:function:: paddle.geometric.segment_min(data, segment_ids, name=None) 分段求最小值函数。 diff --git a/docs/api/paddle/geometric/send_uv_cn.rst b/docs/api/paddle/geometric/send_uv_cn.rst index f4c9540e490..c842d250bce 100644 --- a/docs/api/paddle/geometric/send_uv_cn.rst +++ b/docs/api/paddle/geometric/send_uv_cn.rst @@ -1,6 +1,6 @@ .. _cn_api_geometric_send_uv: -send_ue_recv +send_uv ------------------------------- .. py:function:: paddle.geometric.send_uv(x, y, src_index, dst_index, message_op="add", name=None) From de59764cf5e1dd652d12af4529c568f331798b13 Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Wed, 21 Sep 2022 16:53:13 +0800 Subject: [PATCH 3/8] fix doc --- docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst | 2 +- docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst | 2 +- docs/api/paddle/geometric/message_passing/send_uv_cn.rst | 2 +- docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst b/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst index 5104e16acb3..f80338fcadd 100644 --- a/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst +++ b/docs/api/paddle/geometric/message_passing/send_u_recv_cn.rst @@ -5,4 +5,4 @@ send_u_recv .. py:function:: paddle.geometric.message_passing.send_u_recv(x, src_index, dst_index, reduce_op="sum", out_size=None, name=None) -主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_paddle_geometric_send_u_recv` 功能一致。 +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_geometric_send_u_recv` 功能一致。 diff --git a/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst b/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst index c40bc7c6fbc..d6d7e2287d6 100644 --- a/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst +++ b/docs/api/paddle/geometric/message_passing/send_ue_recv_cn.rst @@ -5,4 +5,4 @@ send_ue_recv .. py:function:: paddle.geometric.message_passing.send_ue_recv(x, y, src_index, dst_index, message_op="add", reduce_op="sum", out_size=None, name=None) -主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_paddle_geometric_send_ue_recv` 功能一致。 +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_geometric_send_ue_recv` 功能一致。 diff --git a/docs/api/paddle/geometric/message_passing/send_uv_cn.rst b/docs/api/paddle/geometric/message_passing/send_uv_cn.rst index 1242705158b..ac1b0df95b8 100644 --- a/docs/api/paddle/geometric/message_passing/send_uv_cn.rst +++ b/docs/api/paddle/geometric/message_passing/send_uv_cn.rst @@ -5,4 +5,4 @@ send_uv .. py:function:: paddle.geometric.message_passing.send_uv(x, y, src_index, dst_index, message_op="add", name=None) -主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_paddle_geometric_send_uv` 功能一致。 +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_geometric_send_uv` 功能一致。 diff --git a/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst b/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst index d15ae420775..2018f4e6956 100644 --- a/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst +++ b/docs/api/paddle/geometric/sampling/sample_neighbors_cn.rst @@ -5,4 +5,4 @@ sample_neighbors .. py:function:: paddle.geometric.sampling.sample_neighbors(row, colptr, input_nodes, sample_size=-1, eids=None, return_eids=False, perm_buffer=None, name=None) -主要应用于图学习领域，主要目的是提供高性能图邻居采样方法，与 :ref:`cn_api_paddle_geometric_sample_neighbors` 功能一致。 +主要应用于图学习领域，主要目的是提供高性能图邻居采样方法，与 :ref:`cn_api_geometric_sample_neighbors` 功能一致。 From a11a3c8832cc8b73f39cdfd9493f5b1e84d61957 Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Wed, 21 Sep 2022 13:55:21 +0000 Subject: [PATCH 4/8] add overview --- docs/api/paddle/geometric/Overview_cn.rst | 51 +++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/api/paddle/geometric/Overview_cn.rst diff --git a/docs/api/paddle/geometric/Overview_cn.rst b/docs/api/paddle/geometric/Overview_cn.rst new file mode 100644 index 00000000000..eb3e1ee8d03 --- /dev/null +++ b/docs/api/paddle/geometric/Overview_cn.rst @@ -0,0 +1,51 @@ +.. _cn_overview_paddle_geometric: + +paddle.geometric +--------------------- + +paddle.geometric 目录下包含飞桨框架支持的图领域的相关 API。具体如下： + +- :ref:`高性能图消息传递 ` +- :ref:`高效图采样 ` +- :ref:`数学分段求值 ` + +.. _faster_message_passing: + +高性能图消息传递 +========================== + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.geometric.send_u_recv ` ", "源节点特征消息传递" + " :ref:`paddle.geometric.send_ue_recv ` ", "节点融合边特征消息传递" + " :ref:`paddle.geometric.send_uv ` ", "节点特征消息发送" + " :ref:`paddle.geometric.message_passing.send_u_recv ` ", "源节点特征消息传递" + " :ref:`paddle.geometric.message_passing.send_ue_recv ` ", "节点融合边特征消息传递" + " :ref:`paddle.geometric.message_passing.send_uv ` ", "节点特征消息发送" + +.. _faster_graph_sampling: + +高效图采样 +========================== + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.geometric.sample_neighbors ` ", "无权重邻居采样" + " :ref:`paddle.geometric.sampling.sample_neighbors ` ", "无权重邻居采样" + " :ref:`paddle.geometric.reindex_graph ` ", "同构图场景下的子图重编号" + " :ref:`paddle.geometric.reindex_heter_graph ` ", "异构图场景下的子图重编号" + +.. _math_segment: + +数学分段求值 +========================== + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.geometric.segment_sum ` ", "分段求和" + " :ref:`paddle.geometric.segment_mean ` ", "分段求均值" + " :ref:`paddle.geometric.segment_max ` ", "分段求最大值" + " :ref:`paddle.geometric.segment_min ` ", "分段求最小值" From f6ac6ef9516ad3238828fd7994a09c58cbcaca63 Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Thu, 22 Sep 2022 14:45:58 +0800 Subject: [PATCH 5/8] fix format --- docs/api/paddle/geometric/reindex_graph_cn.rst | 10 +++++----- .../paddle/geometric/reindex_heter_graph_cn.rst | 10 +++++----- docs/api/paddle/geometric/sample_neighbors_cn.rst | 14 +++++++------- docs/api/paddle/geometric/segment_max_cn.rst | 2 +- docs/api/paddle/geometric/segment_mean_cn.rst | 2 +- docs/api/paddle/geometric/segment_min_cn.rst | 2 +- docs/api/paddle/geometric/segment_sum_cn.rst | 2 +- docs/api/paddle/geometric/send_u_recv_cn.rst | 10 +++++----- docs/api/paddle/geometric/send_ue_recv_cn.rst | 14 +++++++------- docs/api/paddle/geometric/send_uv_cn.rst | 8 ++++---- 10 files changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/api/paddle/geometric/reindex_graph_cn.rst b/docs/api/paddle/geometric/reindex_graph_cn.rst index 5aed51fdb1d..c3323005995 100644 --- a/docs/api/paddle/geometric/reindex_graph_cn.rst +++ b/docs/api/paddle/geometric/reindex_graph_cn.rst @@ -18,11 +18,11 @@ reindex_graph 参数 ::::::::: - - x (Tensor) - 输入的中心节点原始编号，数据类型为：int32、int64。 - - neighbors (Tensor) - 中心节点的邻居节点编号，数据类型为：int32、int64。 - - count (Tensor) - 中心节点各自的邻居数目，数据类型为：int32。 - - value_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。 - - index_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。如果需要使用加速重编号过程，则 ``value_buffer`` 和 ``index_buffer`` 均不可为空。 + - **x** (Tensor) - 输入的中心节点原始编号，数据类型为：int32、int64。 + - **neighbors** (Tensor) - 中心节点的邻居节点编号，数据类型为：int32、int64。 + - **count** (Tensor) - 中心节点各自的邻居数目，数据类型为：int32。 + - **value_buffer** (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。 + - **index_buffer** (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。如果需要使用加速重编号过程，则 ``value_buffer`` 和 ``index_buffer`` 均不可为空。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst index dfbcc98c325..283ec021a33 100644 --- a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst +++ b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst @@ -19,11 +19,11 @@ reindex_heter_graph 参数 ::::::::: - - x (Tensor) - 输入的中心节点原始编号，数据类型为：int32、int64。 - - neighbors (list | tuple) - 中心节点对应到各个异构图中的邻居节点编号，数据类型为：int32、int64。 - - count (list | tuple) - 中心节点对应到各个异构图中的邻居数目，数据类型为：int32。 - - value_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。 - - index_buffer (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。如果需要使用加速重编号过程，则 ``value_buffer`` 和 ``index_buffer`` 均不可为空。 + - **x** (Tensor) - 输入的中心节点原始编号，数据类型为：int32、int64。 + - **neighbors** (list | tuple) - 中心节点对应到各个异构图中的邻居节点编号，数据类型为：int32、int64。 + - **count** (list | tuple) - 中心节点对应到各个异构图中的邻居数目，数据类型为：int32。 + - **value_buffer** (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。 + - **index_buffer** (Tensor，可选) - 用于快速哈希索引的缓存 Tensor，可加速重编号过程。数据类型为 int32，并且应当事先填充为-1。默认值为 None。如果需要使用加速重编号过程，则 ``value_buffer`` 和 ``index_buffer`` 均不可为空。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/sample_neighbors_cn.rst b/docs/api/paddle/geometric/sample_neighbors_cn.rst index d4d3add0083..efdbdc258bf 100644 --- a/docs/api/paddle/geometric/sample_neighbors_cn.rst +++ b/docs/api/paddle/geometric/sample_neighbors_cn.rst @@ -9,13 +9,13 @@ sample_neighbors 参数 ::::::::: - - row (Tensor) - 输入原始图的 CSC 格式的行信息，数据类型为：int32、int64，形状为[num_edges, 1] 或 [num_edges]。 - - colptr (Tensor) - 输入原始图的 CSC 格式的压缩列信息，数据类型应当与 ``row`` 一致，形状为[num_nodes + 1, 1]或 [num_nodes + 1]。 - - input_nodes (Tensor) - 需进行邻居采样的中心节点信息，数据类型应当与 ``row`` 一致。 - - sample_size (int) - 采样邻居个数。默认值为-1，表示采样输入中心节点的所有邻居。 - - eids (Tensor，可选) - 输入原始图在 CSC 格式下的边编号信息。如果 ``return_eids`` 为 True，则不能为空。数据类型应当与 ``row`` 一致。默认为 None，表示不需要返回边编号信息。 - - return_eids (bool) - 是否返回采样后对应的原始边编号信息，默认为 False。 - - perm_buffer (Tensor，可选) - Fisher-yates 采样方法需要用到的缓存 Tensor。如果需使用高性能图采样方法，则不能为空。数据类型应当与 ``row`` 一致，形状为[num_edges]，填充内容为 0 至 num_edges 的顺序递增序列。 + - **row** (Tensor) - 输入原始图的 CSC 格式的行信息，数据类型为：int32、int64，形状为[num_edges, 1] 或 [num_edges]。 + - **colptr** (Tensor) - 输入原始图的 CSC 格式的压缩列信息，数据类型应当与 ``row`` 一致，形状为[num_nodes + 1, 1]或 [num_nodes + 1]。 + - **input_nodes** (Tensor) - 需进行邻居采样的中心节点信息，数据类型应当与 ``row`` 一致。 + - **sample_size** (int) - 采样邻居个数。默认值为-1，表示采样输入中心节点的所有邻居。 + - **eids** (Tensor，可选) - 输入原始图在 CSC 格式下的边编号信息。如果 ``return_eids`` 为 True，则不能为空。数据类型应当与 ``row`` 一致。默认为 None，表示不需要返回边编号信息。 + - **return_eids** (bool) - 是否返回采样后对应的原始边编号信息，默认为 False。 + - **perm_buffer** (Tensor，可选) - Fisher-yates 采样方法需要用到的缓存 Tensor。如果需使用高性能图采样方法，则不能为空。数据类型应当与 ``row`` 一致，形状为[num_edges]，填充内容为 0 至 num_edges 的顺序递增序列。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/segment_max_cn.rst b/docs/api/paddle/geometric/segment_max_cn.rst index 1484728b781..9c7c545b382 100644 --- a/docs/api/paddle/geometric/segment_max_cn.rst +++ b/docs/api/paddle/geometric/segment_max_cn.rst @@ -21,7 +21,7 @@ segment_max 参数 ::::::::: - **data** (Tensor) - 张量，数据类型为 float32、float64。 - - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/segment_mean_cn.rst b/docs/api/paddle/geometric/segment_mean_cn.rst index 4b97673ddea..57988f029c3 100644 --- a/docs/api/paddle/geometric/segment_mean_cn.rst +++ b/docs/api/paddle/geometric/segment_mean_cn.rst @@ -21,7 +21,7 @@ segment_mean 参数 ::::::::: - **data** (Tensor) - 张量，数据类型为 float32、float64。 - - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/segment_min_cn.rst b/docs/api/paddle/geometric/segment_min_cn.rst index 7dfd854d2f4..afdc60e542f 100644 --- a/docs/api/paddle/geometric/segment_min_cn.rst +++ b/docs/api/paddle/geometric/segment_min_cn.rst @@ -21,7 +21,7 @@ segment_min 参数 ::::::::: - **data** (Tensor) - 张量，数据类型为 float32、float64。 - - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/segment_sum_cn.rst b/docs/api/paddle/geometric/segment_sum_cn.rst index a7f4ba7d65c..88a61038082 100644 --- a/docs/api/paddle/geometric/segment_sum_cn.rst +++ b/docs/api/paddle/geometric/segment_sum_cn.rst @@ -22,7 +22,7 @@ segment_sum ::::::::: - **data** (Tensor) - 张量，数据类型为 float32、float64。 - - **segment_ids** (Tensor) - 一维张量，与输入数据`data`的第一维大小相同，表示`data`分段位置，单调非减。合法的数据类型为 int32、int64。 + - **segment_ids** (Tensor) - 一维张量，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/send_u_recv_cn.rst b/docs/api/paddle/geometric/send_u_recv_cn.rst index f0b909da06b..94c4459d6f7 100644 --- a/docs/api/paddle/geometric/send_u_recv_cn.rst +++ b/docs/api/paddle/geometric/send_u_recv_cn.rst @@ -29,11 +29,11 @@ send_u_recv 参数 ::::::::: - - x (Tensor) - 输入的节点特征 Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 - - src_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。 - - dst_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 - - reduce_op (str) - 不同更新方式，包括 sum、mean、max、min。默认值为 sum。 - - out_size (int64 | Tensor | None) - 可以通过根据实际需求设置 ``out_size`` 来改变实际输出形状。默认值为 None，表示这个参数将不会被使用。注意，``out_size`` 的值必须等于或大于 ``max(dst_index) + 1`` 。 + - **x** (Tensor) - 输入的节点特征 Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - **src_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。 + - **dst_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 + - **reduce_op** (str) - 不同更新方式，包括 sum、mean、max、min。默认值为 sum。 + - **out_size** (int64 | Tensor | None) - 可以通过根据实际需求设置 ``out_size`` 来改变实际输出形状。默认值为 None，表示这个参数将不会被使用。注意，``out_size`` 的值必须等于或大于 ``max(dst_index) + 1`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/send_ue_recv_cn.rst b/docs/api/paddle/geometric/send_ue_recv_cn.rst index cf01a5c120d..faf8c628227 100644 --- a/docs/api/paddle/geometric/send_ue_recv_cn.rst +++ b/docs/api/paddle/geometric/send_ue_recv_cn.rst @@ -33,13 +33,13 @@ send_ue_recv 参数 ::::::::: - - x (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 - - y (Tensor) - 输入的边特征 Tensor，数据类型为：float32、float64、int32、int64。数据类型需与 ``x`` 相同。另外，我们在 GPU 计算中支持 float16。 - - src_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。 - - dst_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 - - message_op (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 - - reduce_op (str) - 不同更新方式，包括 sum、mean、max、min。默认值为 sum。 - - out_size (int64 | Tensor | None) - 可以通过根据实际需求设置 ``out_size`` 来改变实际输出形状。默认值为 None，表示这个参数将不会被使用。注意，``out_size`` 的值必须等于或大于 ``max(dst_index) + 1`` 。 + - **x** (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - **y** (Tensor) - 输入的边特征 Tensor，数据类型为：float32、float64、int32、int64。数据类型需与 ``x`` 相同。另外，我们在 GPU 计算中支持 float16。 + - **src_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。 + - **dst_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 + - **message_op** (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 + - **reduce_op** (str) - 不同更新方式，包括 sum、mean、max、min。默认值为 sum。 + - **out_size** (int64 | Tensor | None) - 可以通过根据实际需求设置 ``out_size`` 来改变实际输出形状。默认值为 None，表示这个参数将不会被使用。注意，``out_size`` 的值必须等于或大于 ``max(dst_index) + 1`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/geometric/send_uv_cn.rst b/docs/api/paddle/geometric/send_uv_cn.rst index c842d250bce..73cfb726e1d 100644 --- a/docs/api/paddle/geometric/send_uv_cn.rst +++ b/docs/api/paddle/geometric/send_uv_cn.rst @@ -27,10 +27,10 @@ send_uv 参数 ::::::::: - - x (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 - - src_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。 - - dst_index (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 - - message_op (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 + - **x** (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - **src_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。 + - **dst_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 + - **message_op** (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 From 3f51ac8930e43df7c246719fff397d909bc3e9e3 Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Mon, 26 Sep 2022 14:22:07 +0800 Subject: [PATCH 6/8] update overview --- docs/api/paddle/geometric/Overview_cn.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/paddle/geometric/Overview_cn.rst b/docs/api/paddle/geometric/Overview_cn.rst index eb3e1ee8d03..b6a2d5fc4c3 100644 --- a/docs/api/paddle/geometric/Overview_cn.rst +++ b/docs/api/paddle/geometric/Overview_cn.rst @@ -17,12 +17,12 @@ paddle.geometric 目录下包含飞桨框架支持的图领域的相关 API。 .. csv-table:: :header: "API 名称", "API 功能" - " :ref:`paddle.geometric.send_u_recv ` ", "源节点特征消息传递" + " :ref:`paddle.geometric.send_u_recv ` ", "节点特征消息传递" " :ref:`paddle.geometric.send_ue_recv ` ", "节点融合边特征消息传递" - " :ref:`paddle.geometric.send_uv ` ", "节点特征消息发送" - " :ref:`paddle.geometric.message_passing.send_u_recv ` ", "源节点特征消息传递" + " :ref:`paddle.geometric.send_uv ` ", "源节点与目标节点消息发送并计算" + " :ref:`paddle.geometric.message_passing.send_u_recv ` ", "节点特征消息传递" " :ref:`paddle.geometric.message_passing.send_ue_recv ` ", "节点融合边特征消息传递" - " :ref:`paddle.geometric.message_passing.send_uv ` ", "节点特征消息发送" + " :ref:`paddle.geometric.message_passing.send_uv ` ", "源节点与目标节点消息发送并计算" .. _faster_graph_sampling: From 4b377caf85d170b3d25c017e5cace1ec9e3483de Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Tue, 11 Oct 2022 02:54:21 +0000 Subject: [PATCH 7/8] fix code style --- docs/api/paddle/geometric/reindex_graph_cn.rst | 2 +- docs/api/paddle/geometric/reindex_heter_graph_cn.rst | 2 +- docs/api/paddle/geometric/send_ue_recv_cn.rst | 2 +- docs/api/paddle/geometric/send_uv_cn.rst | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/paddle/geometric/reindex_graph_cn.rst b/docs/api/paddle/geometric/reindex_graph_cn.rst index c3323005995..cbd7d64469d 100644 --- a/docs/api/paddle/geometric/reindex_graph_cn.rst +++ b/docs/api/paddle/geometric/reindex_graph_cn.rst @@ -7,7 +7,7 @@ reindex_graph 主要应用于图学习领域，需要与图采样相关的 API 配合使用，主要处理同构图场景。其主要目的是对输入的中心节点信息和邻居信息进行从 0 开始的重新编号，以方便后续的图模型子图训练。 -**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从0进行编号。 +**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从 0 进行编号。 以输入 x = [0, 1, 2] 作为例子解释。假设我们有邻居 neighbors = [8, 9, 0, 4, 7, 6, 7]，以及邻居数量 count = [2, 3, 2]。 则可以得知节点 0 的邻居为 [8, 9]，节点 1 的邻居为 [0, 4, 7]，节点 2 的邻居为 [6, 7]。经过此 API 计算后，共计会返回三个结果： diff --git a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst index 283ec021a33..62320b62a96 100644 --- a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst +++ b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst @@ -7,7 +7,7 @@ reindex_heter_graph 主要应用于图学习领域，需要与图采样相关的 API 配合使用，主要处理异构图场景。其主要目的是对输入的中心节点信息和邻居信息进行从 0 开始的重新编号，以方便后续的图模型子图训练。 -**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从0进行编号。 +**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从 0 进行编号。 以输入 x = [0, 1, 2] 作为例子解释。对于异构图 A ，假设我们有邻居 neighbors = [8, 9, 0, 4, 7, 6, 7]，以及邻居数量 count = [2, 3, 2]； 则可以得知节点 0 的邻居为 [8, 9]，节点 1 的邻居为 [0, 4, 7]，节点 2 的邻居为 [6, 7]。对于异构图 B，假设有邻居 neighbors = [0, 2, 3, 5, 1]， diff --git a/docs/api/paddle/geometric/send_ue_recv_cn.rst b/docs/api/paddle/geometric/send_ue_recv_cn.rst index faf8c628227..203c55856ac 100644 --- a/docs/api/paddle/geometric/send_ue_recv_cn.rst +++ b/docs/api/paddle/geometric/send_ue_recv_cn.rst @@ -33,7 +33,7 @@ send_ue_recv 参数 ::::::::: - - **x** (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - **x** (Tensor) - 输入的节点特征 Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 - **y** (Tensor) - 输入的边特征 Tensor，数据类型为：float32、float64、int32、int64。数据类型需与 ``x`` 相同。另外，我们在 GPU 计算中支持 float16。 - **src_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。 - **dst_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 diff --git a/docs/api/paddle/geometric/send_uv_cn.rst b/docs/api/paddle/geometric/send_uv_cn.rst index 73cfb726e1d..efb30e49f23 100644 --- a/docs/api/paddle/geometric/send_uv_cn.rst +++ b/docs/api/paddle/geometric/send_uv_cn.rst @@ -5,7 +5,7 @@ send_uv .. py:function:: paddle.geometric.send_uv(x, y, src_index, dst_index, message_op="add", name=None) -主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗。其中，``x`` 作为输入的节点特征 Tensor，首先利用 ``src_index`` 作为索引来 gather 出在 ``x`` 中相应位置的数据，接着利用 ``dst_index`` gather出 ``y`` 中相应位置的数据，再通过 ``message_op`` 确认计算方式，最终返回。其中，``message_op`` 包括另外 add、sub、mul、div共计四种计算方式。 +主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗。其中，``x`` 作为输入的节点特征 Tensor，首先利用 ``src_index`` 作为索引来 gather 出在 ``x`` 中相应位置的数据，接着利用 ``dst_index`` gather 出 ``y`` 中相应位置的数据，再通过 ``message_op`` 确认计算方式，最终返回。其中，``message_op`` 包括另外 add、sub、mul、div 共计四种计算方式。 .. code-block:: text @@ -27,7 +27,7 @@ send_uv 参数 ::::::::: - - **x** (Tensor) - 输入的节点特征Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 + - **x** (Tensor) - 输入的节点特征 Tensor，数据类型为：float32、float64、int32、int64。另外，我们在 GPU 计算中支持 float16。 - **src_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。 - **dst_index** (Tensor) - 1-D Tensor，数据类型为：int32、int64。注意：``dst_index`` 的形状应当与 ``src_index`` 一致。 - **message_op** (str) - 不同计算方式，包括 add、sub、mul、div。默认值为 add。 From c2e4e5380d644dac23f0d25439ea2a7f585f65be Mon Sep 17 00:00:00 2001 From: DesmonDay <908660116@qq.com> Date: Tue, 11 Oct 2022 03:46:11 +0000 Subject: [PATCH 8/8] add note --- docs/api/paddle/geometric/reindex_graph_cn.rst | 3 ++- docs/api/paddle/geometric/reindex_heter_graph_cn.rst | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/api/paddle/geometric/reindex_graph_cn.rst b/docs/api/paddle/geometric/reindex_graph_cn.rst index cbd7d64469d..91eec01f138 100644 --- a/docs/api/paddle/geometric/reindex_graph_cn.rst +++ b/docs/api/paddle/geometric/reindex_graph_cn.rst @@ -7,7 +7,8 @@ reindex_graph 主要应用于图学习领域，需要与图采样相关的 API 配合使用，主要处理同构图场景。其主要目的是对输入的中心节点信息和邻居信息进行从 0 开始的重新编号，以方便后续的图模型子图训练。 -**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从 0 进行编号。 +.. note:: + 输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从 0 进行编号。 以输入 x = [0, 1, 2] 作为例子解释。假设我们有邻居 neighbors = [8, 9, 0, 4, 7, 6, 7]，以及邻居数量 count = [2, 3, 2]。 则可以得知节点 0 的邻居为 [8, 9]，节点 1 的邻居为 [0, 4, 7]，节点 2 的邻居为 [6, 7]。经过此 API 计算后，共计会返回三个结果： diff --git a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst index 62320b62a96..2055cc7e604 100644 --- a/docs/api/paddle/geometric/reindex_heter_graph_cn.rst +++ b/docs/api/paddle/geometric/reindex_heter_graph_cn.rst @@ -7,7 +7,8 @@ reindex_heter_graph 主要应用于图学习领域，需要与图采样相关的 API 配合使用，主要处理异构图场景。其主要目的是对输入的中心节点信息和邻居信息进行从 0 开始的重新编号，以方便后续的图模型子图训练。 -**注意**：输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从 0 进行编号。 +.. note:: + 输入 ``x`` 中的元素需保证是独有的，否则可能会带来一些潜在的错误。输入的节点将会和邻居节点一同从 0 进行编号。 以输入 x = [0, 1, 2] 作为例子解释。对于异构图 A ，假设我们有邻居 neighbors = [8, 9, 0, 4, 7, 6, 7]，以及邻居数量 count = [2, 3, 2]； 则可以得知节点 0 的邻居为 [8, 9]，节点 1 的邻居为 [0, 4, 7]，节点 2 的邻居为 [6, 7]。对于异构图 B，假设有邻居 neighbors = [0, 2, 3, 5, 1]，