[API Compatiblity] Support paddle.linalg.solve, paddle.nn.functional.normalize, paddle.quantile (PaddlePaddle#76470)

* add Decorator

* fix out

* fix UT

* fix

* fix out

Author: fangfangssj

python/paddle/_paddle_docs.py

@@ -2460,7 +2460,7 @@ def bmm(
 """,
     """
 def logical_and(
-    x: Tensor, y: Tensor, out: Tensor | None = None, name: str | None = None
+    x: Tensor, y: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2511,7 +2511,7 @@ def logical_and(
 """,
     """
 def logical_or(
-    x: Tensor, y: Tensor, out: Tensor | None = None, name: str | None = None
+    x: Tensor, y: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2557,7 +2557,7 @@ def logical_or(
 """,
     """
 def logical_not(
-    x: Tensor, out: Tensor | None = None, name: str | None = None
+    x: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2608,7 +2608,7 @@ def logical_not(
 """,
     """
 def logical_xor(
-    x: Tensor, y: Tensor, out: Tensor | None = None, name: str | None = None
+    x: Tensor, y: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2705,7 +2705,7 @@ def dot(
 """,
     """
 def tanh(
-    x: Tensor, *, out: Tensor | None = None, name: str | None = None,
+    x: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2745,7 +2745,7 @@ def tanh(
 """,
     """
 def exp(
-    x: Tensor, *, out: Tensor | None = None, name: str | None = None
+    x: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2785,7 +2785,7 @@ def exp(
 """,
     """
 def expm1(
-    x: Tensor, *, out: Tensor | None = None, name: str | None = None
+    x: Tensor, name: str | None = None, *, out: Tensor | None = None
 ) -> Tensor
 """,
 )
@@ -2917,7 +2917,7 @@ def diagonal(
 """,
     """
 def round(
-    x: Tensor, decimals = 0, *, out: Tensor | None = None, name: str | None = None,
+    x: Tensor, decimals: int = 0, name: str | None = None, *, out: Tensor | None = None,
 ) -> Tensor
 """,
 )

python/paddle/nn/functional/norm.py

@@ -28,6 +28,7 @@
     in_pir_mode,
 )
 from paddle.utils.decorator_utils import (
+    ParamAliasDecorator,
     param_two_alias,
 )
 
@@ -49,12 +50,15 @@
 __all__ = []
 
 
+@ParamAliasDecorator({"x": ["input"], "axis": ["dim"], "epsilon": ["eps"]})
 def normalize(
     x: Tensor,
     p: float = 2,
     axis: int = 1,
     epsilon: float = 1e-12,
     name: str | None = None,
+    *,
+    out: Tensor | None = None,
 ) -> Tensor:
     r"""
     Normalize ``x`` along dimension ``axis`` using :math:`L_p` norm. This layer computes
@@ -68,13 +72,16 @@ def normalize(
 
     where, :math:`\sum_i{\lvert x_i \rvert^p}` is calculated along the ``axis`` dimension.
 
-
     Parameters:
         x (Tensor): The input tensor could be N-D tensor, and the input data type could be float32 or float64.
+            Alias: ``input``.
         p (float|int, optional): The exponent value in the norm formulation. Default: 2.
         axis (int, optional): The axis on which to apply normalization. If `axis < 0`, the dimension to normalization is `x.ndim + axis`. -1 is the last dimension.
+            Alias: ``dim``.
         epsilon (float, optional): Small float added to denominator to avoid dividing by zero. Default is 1e-12.
+            Alias: ``esp``.
         name (str|None, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`.
+        out (Tensor|None, optional): The output tensor. Default: None.
 
     Returns:
         Tensor, the output has the same shape and data type with ``x``.
@@ -110,13 +117,13 @@ def normalize(
 
     if in_dygraph_mode():
         eps = paddle.full(shape=[1], fill_value=epsilon, dtype=x.dtype)
-        out = _C_ops.p_norm(x, float(p), axis, epsilon, True, False)
-        return x / _C_ops.maximum(out, eps)
+        ret = _C_ops.p_norm(x, float(p), axis, epsilon, True, False)
+        ret = x / _C_ops.maximum(ret, eps)
 
     elif in_pir_mode():
         eps = paddle.full(shape=[1], fill_value=epsilon, dtype=x.dtype)
-        out = _C_ops.p_norm(x, float(p), axis, epsilon, True, False)
-        return paddle.divide(x, _C_ops.maximum(out, eps), name=name)
+        ret = _C_ops.p_norm(x, float(p), axis, epsilon, True, False)
+        ret = paddle.divide(x, _C_ops.maximum(ret, eps), name=name)
 
     else:
         check_type(p, 'p', (float, int), 'normalize')
@@ -142,7 +149,12 @@ def normalize(
         )
         eps = out.block.create_var(dtype=out.dtype)
         eps = paddle.full(shape=[1], fill_value=epsilon, dtype=out.dtype)
-        return paddle.divide(x, paddle.maximum(out, eps), name=name)
+        out = paddle.divide(x, paddle.maximum(out, eps), name=name)
+
+    if out is not None:
+        paddle.assign(ret, out)
+        return out
+    return ret
 
 
 def batch_norm(

python/paddle/tensor/linalg.py

@@ -28,6 +28,7 @@
 from paddle.utils.decorator_utils import (
     ParamAliasDecorator,
     VariableArgsDecorator,
+    param_two_alias,
     transpose_decorator,
 )
 from paddle.utils.inplace_utils import inplace_apis_in_dygraph_only
@@ -4178,8 +4179,14 @@ def _transpose_last_2dim(x):
     return x
 
 
+@param_two_alias(["x", "A"], ["y", "B"])
 def solve(
-    x: Tensor, y: Tensor, left: bool = True, name: str | None = None
+    x: Tensor,
+    y: Tensor,
+    left: bool = True,
+    name: str | None = None,
+    *,
+    out: Tensor | None = None,
 ) -> Tensor:
     r"""
 
@@ -4199,12 +4206,13 @@ def solve(
 
     Args:
         x (Tensor): A square matrix or a batch of square matrices. Its shape should be ``[*, M, M]``, where ``*`` is zero or
-            more batch dimensions. Its data type should be float32 or float64.
+            more batch dimensions. Its data type should be float32 or float64. Alias: ``A``.
         y (Tensor): A vector/matrix or a batch of vectors/matrices. Its shape should be ``[*, M, K]``, where ``*`` is zero or
-            more batch dimensions. Its data type should be float32 or float64.
+            more batch dimensions. Its data type should be float32 or float64. Alias: ``B``.
         left (bool, optional): Whether to solve the system :math:`X * Out = Y` or :math:`Out * X = Y`. Default: True.
         name (str|None, optional): Name for the operation (optional, default is None).
             For more information, please refer to :ref:`api_guide_Name`.
+        out (Tensor|None, optional): The output tensor. Default: None.
 
     Returns:
         Tensor: The solution of a square system of linear equations with a unique solution for input 'x' and 'y'.
@@ -4234,7 +4242,7 @@ def solve(
         y = _transpose_last_2dim(y)
 
     if in_dynamic_or_pir_mode():
-        out = _C_ops.solve(x, y)
+        ret = _C_ops.solve(x, y)
     else:
         inputs = {"X": [x], "Y": [y]}
         helper = LayerHelper("solve", **locals())
@@ -4247,8 +4255,10 @@ def solve(
         )
 
     if not left:
-        out = _transpose_last_2dim(out)
-    return out
+        ret = _transpose_last_2dim(ret)
+    if out is not None:
+        paddle.assign(ret, out)
+    return ret
 
 
 def triangular_solve(

python/paddle/tensor/stat.py

@@ -717,6 +717,7 @@ def _compute_quantile(
     keepdim: bool = False,
     interpolation: _Interpolation = "linear",
     ignore_nan: bool = False,
+    out: Tensor | None = None,
 ) -> Tensor:
     """
     Compute the quantile of the input along the specified axis.
@@ -742,6 +743,7 @@ def _compute_quantile(
         ignore_nan: (bool, optional): Whether to ignore NaN of input Tensor.
             If ``ignore_nan`` is True, it will calculate nanquantile.
             Otherwise it will calculate quantile. Default is False.
+        out (Tensor|None, optional): The output tensor. Default: None.
 
     Returns:
         Tensor, results of quantile along ``axis`` of ``x``.
@@ -879,27 +881,34 @@ def _compute_index(index):
 
     # TODO(chenjianye): replace the for-loop to directly take elements.
     for index in indices:
-        out = _compute_index(index)
+        ret = _compute_index(index)
         if not keepdim:
-            out = paddle.squeeze(out, axis=axis)
+            ret = paddle.squeeze(ret, axis=axis)
         else:
-            out = out.reshape(out_shape)
-        outputs.append(out)
+            ret = ret.reshape(out_shape)
+        outputs.append(ret)
 
     if len(outputs) > 1:
         outputs = paddle.stack(outputs, 0)
     else:
         outputs = outputs[0]
-    # return outputs.astype(x.dtype)
+
+    if out is not None:
+        paddle.assign(outputs, out)
+        return out
     return outputs
 
 
+@param_two_alias(["x", "input"], ["axis", "dim"])
 def quantile(
     x: Tensor,
     q: float | Sequence[float] | Tensor,
     axis: int | list[int] | None = None,
     keepdim: bool = False,
     interpolation: _Interpolation = "linear",
+    name: str | None = None,
+    *,
+    out: Tensor | None = None,
 ) -> Tensor:
     """
     Compute the quantile of the input along the specified axis.
@@ -925,6 +934,8 @@ def quantile(
             lower, midpoint and nearest. Default is linear.
         name (str, optional): Name for the operation (optional, default is None).
             For more information, please refer to :ref:`api_guide_Name`.
+        out (Tensor|None, optional): The output tensor. Default: None.
+
 
     Returns:
         Tensor, results of quantile along ``axis`` of ``x``.
@@ -975,6 +986,7 @@ def quantile(
         keepdim=keepdim,
         interpolation=interpolation,
         ignore_nan=False,
+        out=out,
     )
 
 

test/legacy_test/test_normalize.py

@@ -102,5 +102,98 @@ def test_gpu(self):
             self.run_static(use_gpu=True)
 
 
+class TestNormalizeAPI_Compatibility(unittest.TestCase):
+    def setUp(self):
+        np.random.seed(2025)
+        self.places = ['cpu', get_device_place()]
+        self.shape = [2, 3, 4]
+        self.dtype = "float32"
+        self.init_data()
+
+    def init_data(self):
+        self.np_x = np.random.rand(*self.shape).astype(self.dtype)
+        self.p = 2
+        self.axis = 1
+        self.epsilon = 1e-12
+
+    def test_dygraph_Compatibility(self):
+        paddle.disable_static()
+        x = paddle.to_tensor(self.np_x)
+        paddle_dygraph_out = []
+        # Position args (args)
+        out1 = paddle.nn.functional.normalize(
+            x, self.p, self.axis, self.epsilon
+        )
+        paddle_dygraph_out.append(out1)
+        # Key words args (kwargs) for paddle
+        out2 = paddle.nn.functional.normalize(
+            x=x, p=self.p, axis=self.axis, epsilon=self.epsilon
+        )
+        paddle_dygraph_out.append(out2)
+        # Key words args for torch compatibility
+        out3 = paddle.nn.functional.normalize(
+            input=x, p=self.p, dim=self.axis, eps=self.epsilon
+        )
+        paddle_dygraph_out.append(out3)
+        # Key words args for out
+        out4 = paddle.zeros_like(x)
+        paddle.nn.functional.normalize(
+            x, self.p, self.axis, self.epsilon, out=out4
+        )
+        paddle_dygraph_out.append(out4)
+        # Numpy reference output
+        ref_out = self.np_x / np.maximum(
+            np.linalg.norm(
+                self.np_x, ord=self.p, axis=self.axis, keepdims=True
+            ),
+            self.epsilon,
+        )
+
+        for out in paddle_dygraph_out:
+            np.testing.assert_allclose(
+                ref_out, out.numpy(), rtol=1e-05, atol=1e-08
+            )
+        paddle.enable_static()
+
+    def test_static_Compatibility(self):
+        paddle.enable_static()
+        main = paddle.static.Program()
+        startup = paddle.static.Program()
+        with paddle.base.program_guard(main, startup):
+            x = paddle.static.data(name="x", shape=self.shape, dtype=self.dtype)
+            # Position args (args)
+            out1 = paddle.nn.functional.normalize(
+                x, self.p, self.axis, self.epsilon
+            )
+            # Key words args (kwargs) for paddle
+            out2 = paddle.nn.functional.normalize(
+                x=x, p=self.p, axis=self.axis, epsilon=self.epsilon
+            )
+            # Key words args for torch compatibility
+            out3 = paddle.nn.functional.normalize(
+                input=x, p=self.p, dim=self.axis, eps=self.epsilon
+            )
+            # Numpy reference output
+            ref_out = self.np_x / np.maximum(
+                np.linalg.norm(
+                    self.np_x, ord=self.p, axis=self.axis, keepdims=True
+                ),
+                self.epsilon,
+            )
+
+            fetch_list = [out1, out2, out3]
+            for place in self.places:
+                exe = paddle.base.Executor(place)
+                fetches = exe.run(
+                    main,
+                    feed={"x": self.np_x},
+                    fetch_list=fetch_list,
+                )
+                for out in fetches:
+                    np.testing.assert_allclose(
+                        out, ref_out, rtol=1e-05, atol=1e-08
+                    )
+
+
 if __name__ == "__main__":
     unittest.main()