update rfc

Author: ADream-ki

rfcs/APIs/20240326_api_design_for_ormqr.md

@@ -1,12 +1,12 @@
 # paddle_ormqr 设计文档
 
-| API 名称                                                          | paddle.ormqr                            |
-| ----------------------------------------------------------------- | --------------------------------------- |
-| 提交作者 `<input type="checkbox" class="rowselector hidden">`     | Chen-Lun-Hao                            |
-| 提交时间 `<input type="checkbox" class="rowselector hidden">`     | 2024-03-27                              |
-| 版本号                                                            | V2.0                                    |
-| 依赖飞桨版本 `<input type="checkbox" class="rowselector hidden">` | develop                                 |
-| 文件名                                                            | 20240326_api_design_for_ormqr.md `<br>` |
+| API 名称     | paddle.ormqr                     |
+| ------------ | -------------------------------- |
+| 提交作者     | Chen-Lun-Hao                     |
+| 提交时间     | 2024-03-27                       |
+| 版本号       | V2.0                             |
+| 依赖飞桨版本 | develop                          |
+| 文件名       | 20240326_api_design_for_ormqr.md |
 
 # 一、概述
 
@@ -37,7 +37,7 @@
 
 ## PyTorch
 
-PyTorch 中有 API `torch.ormqr(input, tau, other, left=True, transpose=False, *, out=None) → Tensoor` 以及对应的 `torch.Tensor.ormqr`
+PyTorch 中有 API `torch.ormqr(input, tau, other, left=True, transpose=False, *, out=None) → Tensor` 以及对应的 `torch.Tensor.ormqr`
 
 其介绍为：
 
@@ -132,6 +132,75 @@ MindSpore 中有 `mindspore.ops.orqmr` 此接口：
 https://www.mindspore.cn/docs/zh-CN/master/_modules/mindspore/ops/function/math_func.html#ormqr
 
 ```python
+class Ormqr(Primitive):
+    r"""
+    Computes the matrix-matrix multiplication of a product of Householder matrices with a general matrix.
+    Multiplies a(m, n) matrix C (given by other) with a matrix Q, where Q is represented using Householder
+    reflectors (x, tau), which is the output of geqrf().
+
+    Refer to :func:`mindspore.ops.ormqr` for more details.
+
+    .. warning::
+        This is an experimental API that is subject to change or deletion.
+
+    Args:
+        left (bool, optional): controls the order of multiplication. If ``True`` , compute op(Q)*C.
+            If ``False`` , compute C*op(Q). Default: ``True`` .
+        transpose(bool, optional): controls whether the matrix Q is conjugate transposed or not.Default: ``False`` .
+
+    Inputs:
+        - **x** (Tensor) - Tensor of shape :math:`(*, mn, k)` where the value of mn depending on `left`,
+          When `left` is ``True``, the value of mn is equal to m; otherwise, the value of mn is equal to n.
+          and `*` is zero or more batch dimensions.
+        - **tau** (Tensor) - Tensor of shape :math:`(*, min(mn, k))` where `*` is zero or more batch dimensions,
+          and its type is the same as `x`.
+        - **other** (Tensor) - Tensor of shape :math:`(*, m, n)` where `*` is zero or more batch dimensions,
+          and its type is the same as `x`.
+
+    Outputs:
+        - **y** (Tensor) - the output Tensor, has the same shape and data type as `other`.
+
+    Raises:
+        TypeError: If `x` or `tau` or `other` is not Tensor.
+        TypeError: If dtype of `x` or `tau` or `other` is not one of: float64, float32, complex64, complex128.
+        ValueError: If `x` or `other` is less than 2D.
+        ValueError: If rank(x) - rank(tau) != 1.
+        ValueError: If tau.shape[:-2] != x.shape[:-2]
+        ValueError: If other.shape[:-2] != x.shape[:-2]
+        ValueError: If left == True, other.shape[-2] < tau.shape[-1].
+        ValueError: If left == True, other.shape[-2] != x.shape[-2].
+        ValueError: If left == False, other.shape[-1] < tau.shape[-1].
+        ValueError: If left == False, other.shape[-1] != x.shape[-2].
+
+    Supported Platforms:
+        ``GPU``
+
+    Examples:
+        >>> import mindspore
+        >>> import numpy as np
+        >>> from mindspore import Tensor, ops
+        >>> x = Tensor(np.array([[-114.6, 10.9, 1.1], [-0.304, 38.07, 69.38], [-0.45, -0.17, 62]]), mindspore.float32)
+        >>> tau = Tensor(np.array([1.55, 1.94, 3.0]), mindspore.float32)
+        >>> other = Tensor(np.array([[-114.6, 10.9, 1.1],
+        ...                          [-0.304, 38.07, 69.38],
+        ...                          [-0.45, -0.17, 62]]), mindspore.float32)
+        >>> net = ops.Ormqr()
+        >>> y = net(x, tau, other)
+        >>> print(y)
+        [[  63.82713   -13.823125 -116.28614 ]
+         [ -53.659264  -28.157839  -70.42702 ]
+         [ -79.54292    24.00183   -41.34253 ]]
+    """
+
+    @prim_attr_register
+    def __init__(self, left=True, transpose=False):
+        """Initialize Ormqr"""
+        self.init_prim_io_names(inputs=['x', 'tau', 'other'], outputs=['y'])
+        self.left = validator.check_value_type('left', left, [bool], self.name)
+        self.transpose = validator.check_value_type('transpose', transpose, [bool], self.name)
+        self.add_prim_attr('left', self.left)
+        self.add_prim_attr('transpose', self.transpose)
+
 def _get_cache_prim(cls: Primitive) -> Primitive:
     """
     Wrapper function, get a primitive by it's all args.
@@ -250,15 +319,11 @@ def _get_cache_prim(cls: Primitive) -> Primitive:
 
 # 四、对比分析
 
-对比 PyTorch 与 MindSpore:
-
-- 实现方式不同
-
-  PyTorch 通过 c++ 实现；MindSpore 通过 python 实现。
+在 Pytorch 以及 MindSpore 框架中，他们对于 ormqr 算子的实现方式不同，Pytorch 中使用的是 c++实现，而 MindSpore 中使用的是 python 实现。
 
 # 五、设计思路与实现方案
 
-paddle 目前的算子已经支持矩阵的转置,行列计算等操作，因此，可以使用 paddle 已有算子实现 `ormqr` ，由于要求输入 `input` 与 `othrt` 具有相同的 `ndim`，因此，不需要使用 `decrease_axes` 等参数。
+paddle 目前的算子已经支持矩阵的转置,行列计算等操作，因此，可以使用 paddle 已有算子实现 `ormqr` 。
 
 ## 命名与参数设计
 
@@ -273,7 +338,7 @@ paddle.orqmr(input, tau, other, left=True, transpose=False)
 - input: (Tensor) shape（\*，mn，k），当 left 为 True 时， mn 的值等于 m，否则 mn 的值等于 n。 \*表示 Tensor 在轴 0 上的长度为 0 或者大于 0。
 - tau: (Tensor) shape（\*，min（mn，k）），其中 \_ 表示 Tensor 在轴 0 上的长度为 0 或者大于 0，其类型与 input 相同。
 - other: (Tensor) shape（\*，m，n），其中 \* 表示 Tensor 在轴 0 上的长度为 0 或者大于 0，其类型与 input 相同。
-- left: (bool, 可选) 决定了矩阵乘积运算的顺序。如果 left 为 True ，计算顺序为 op(Q) x other ，否则，计算顺序为 other x op(Q)。默认值：True。
+- left: (bool, 可选) 决定了矩阵乘积运算的顺序。如果 left 为 True ，计算顺序为 op(Q) ∗ other ，否则，计算顺序为 other \* op(Q)。默认值：True。
 - transpose: (bool, 可选) 如果为 True ，对矩阵 Q 进行共轭转置变换，否则，不对矩阵 Q 进行共轭转置变换。默认值： False。
 
 ## 底层 OP 设计
@@ -282,10 +347,11 @@ paddle.orqmr(input, tau, other, left=True, transpose=False)
 
 # 六、测试和验收的考量
 
-- GPU 测试场景
-- 支持各种 Tensor
-- 需要检查计算正确性
-- 需要检查多维的情况
+- 支持 CPU、GPU 测试场景
+- 支持动态图以及静态图
+- 支持各种 Tensor，如：float32, float64, complex64, complex128
+- 通过对比 mindspore 框架中的 ormqr 算子输出，计算结果是否一致
+- 需要检查二到三维矩阵的计算情况
 
 # 七、可行性分析和排期规划
 
@@ -300,4 +366,5 @@ paddle.orqmr(input, tau, other, left=True, transpose=False)
 # 附件及参考资料
 
 [【Hackathon 6th No.4】为 Paddle 新增 ormqr API](https://github.com/PaddlePaddle/community/pull/668)
-[PyTorch slice_scatter 文档](https://pytorch.org/docs/stable/generated/torch.slice_scatter.html)
+
+[PyTorch ormqr 文档](https://pytorch.org/docs/stable/generated/torch.ormqr.html)