Add paddle.geometric docs (#5292)

docs/api/paddle/geometric/Overview_cn.rst

@@ -0,0 +1,51 @@
+.. _cn_overview_paddle_geometric:
+
+paddle.geometric
+---------------------
+
+paddle.geometric 目录下包含飞桨框架支持的图领域的相关 API。具体如下：
+
+-  :ref:`高性能图消息传递 <faster_message_passing>`
+-  :ref:`高效图采样 <faster_graph_sampling>`
+-  :ref:`数学分段求值 <math_segment>`
+
+.. _faster_message_passing:
+
+高性能图消息传递
+==========================
+
+.. csv-table::
+    :header: "API 名称", "API 功能"
+
+    " :ref:`paddle.geometric.send_u_recv <cn_api_paddle_geometric_send_u_recv>` ", "节点特征消息传递"
+    " :ref:`paddle.geometric.send_ue_recv <cn_api_paddle_geometric_send_ue_recv>` ", "节点融合边特征消息传递"
+    " :ref:`paddle.geometric.send_uv <cn_api_paddle_geometric_send_uv>` ", "源节点与目标节点消息发送并计算"
+    " :ref:`paddle.geometric.message_passing.send_u_recv <cn_api_paddle_geometric_message_passing_send_u_recv>` ", "节点特征消息传递"
+    " :ref:`paddle.geometric.message_passing.send_ue_recv <cn_api_paddle_geometric_message_passing_send_ue_recv>` ", "节点融合边特征消息传递"
+    " :ref:`paddle.geometric.message_passing.send_uv <cn_api_paddle_geometric_message_passing_send_uv>` ", "源节点与目标节点消息发送并计算"
+
+.. _faster_graph_sampling:
+
+高效图采样
+==========================
+
+.. csv-table::
+    :header: "API 名称", "API 功能"
+
+    " :ref:`paddle.geometric.sample_neighbors <cn_api_paddle_geometric_sample_neighbors>` ", "无权重邻居采样"
+    " :ref:`paddle.geometric.sampling.sample_neighbors <cn_api_paddle_geometric_sampling_sample_neighbors>` ", "无权重邻居采样"
+    " :ref:`paddle.geometric.reindex_graph <cn_api_paddle_geometric_reindex_graph>` ", "同构图场景下的子图重编号"
+    " :ref:`paddle.geometric.reindex_heter_graph <cn_api_paddle_geometric_reindex_heter_graph>` ", "异构图场景下的子图重编号"
+
+.. _math_segment:
+
+数学分段求值
+==========================
+
+.. csv-table::
+    :header: "API 名称", "API 功能"
+
+    " :ref:`paddle.geometric.segment_sum <cn_api_paddle_geometric_segment_sum>` ", "分段求和"
+    " :ref:`paddle.geometric.segment_mean <cn_api_paddle_geometric_segment_mean>` ", "分段求均值"
+    " :ref:`paddle.geometric.segment_max <cn_api_paddle_geometric_segment_max>` ", "分段求最大值"
+    " :ref:`paddle.geometric.segment_min <cn_api_paddle_geometric_segment_min>` ", "分段求最小值"

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_geometric_send_u_recv` 功能一致。

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_geometric_send_ue_recv` 功能一致。

docs/api/paddle/geometric/message_passing/send_uv_cn.rst

@@ -0,0 +1,8 @@
+.. _cn_api_geometric_message_passing_send_uv:
+
+send_uv
+-------------------------------
+
+.. py:function:: paddle.geometric.message_passing.send_uv(x, y, src_index, dst_index, message_op="add", name=None)
+
+主要应用于图学习领域，目的是为了减少在消息传递过程中带来的中间变量显存或内存的损耗，与 :ref:`cn_api_geometric_send_uv` 功能一致。

docs/api/paddle/geometric/reindex_graph_cn.rst

@@ -0,0 +1,39 @@
+.. _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 开始的重新编号，以方便后续的图模型子图训练。
+
+.. 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 计算后，共计会返回三个结果：
+    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

docs/api/paddle/geometric/reindex_heter_graph_cn.rst

@@ -0,0 +1,40 @@
+.. _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 开始的重新编号，以方便后续的图模型子图训练。
+
+.. 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]，
+以及邻居数量 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

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

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_geometric_sample_neighbors` 功能一致。

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

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

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

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

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