[API compatibility] add broadcast_shapes api (#74594)

* add broadcast_shapes api

* change judgement

Author: Starrysea996

python/paddle/__init__.py

@@ -406,6 +406,7 @@
     bitwise_right_shift,
     bitwise_right_shift_,
     broadcast_shape,
+    broadcast_shapes,
     cartesian_prod,
     ceil,
     clip,
@@ -1024,6 +1025,7 @@
     'DataParallel',
     'argmin',
     'prod',
+    'broadcast_shapes',
     'broadcast_shape',
     'conj',
     'neg',

python/paddle/tensor/__init__.py

@@ -269,6 +269,7 @@
     bitwise_right_shift,
     bitwise_right_shift_,
     broadcast_shape,
+    broadcast_shapes,
     cartesian_prod,
     ceil,
     ceil_,
@@ -638,6 +639,7 @@
     'isneginf',
     'isposinf',
     'isreal',
+    'broadcast_shapes',
     'broadcast_shape',
     'conj',
     'neg',

python/paddle/tensor/math.py

@@ -5448,6 +5448,53 @@ def any(
         return out
 
 
+def broadcast_shapes(*shapes: Sequence[int]) -> list[int]:
+    """
+    The function returns the shape of doing operation with broadcasting on tensors of shape list.
+
+    Note:
+        If you want know more about broadcasting, please refer to `Introduction to Tensor`_ .
+
+        .. _Introduction to Tensor: ../../guides/beginner/tensor_en.html#chapter5-broadcasting-of-tensor
+
+    Args:
+        *shapes (list[int]|tuple[int]): A shape list of multiple tensors.
+
+
+    Returns:
+        list[int], the result shape.
+
+    Examples:
+        .. code-block:: python
+
+            >>> import paddle
+
+            >>> shape = paddle.broadcast_shapes([2, 1, 3], [1, 3, 1])
+            >>> shape
+            [2, 3, 3]
+
+            >>> # shape = paddle.broadcast_shapes([2, 1, 3], [3, 3, 1])
+            >>> # ValueError (terminated with error message).
+
+            >>> shape = paddle.broadcast_shapes([5, 1, 3], [1, 4, 1], [1, 1, 3])
+            >>> shape
+            [5, 4, 3]
+
+            >>> # shape = paddle.broadcast_shapes([5, 1, 3], [1, 4, 1], [1, 2, 3])
+            >>> # ValueError (terminated with error message).
+
+    """
+    if len(shapes) == 0:
+        return []
+    elif len(shapes) == 1:
+        return list(shapes[0])
+    else:
+        current_shape = list(shapes[0])
+        for next_shape in shapes[1:]:
+            current_shape = broadcast_shape(current_shape, next_shape)
+        return current_shape
+
+
 def broadcast_shape(
     x_shape: Sequence[int], y_shape: Sequence[int]
 ) -> list[int]:

test/legacy_test/test_broadcast_shapes_op.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2025 PaddlePaddle Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+import paddle
+
+
+class TestBroadcastShapes(unittest.TestCase):
+    def test_result(self):
+        shape = paddle.broadcast_shapes(
+            [5, 1, 3, 10],
+            [5, 4, 1, 1],
+            [1, 1, 3, 10],
+            [1, 4, 3, 1],
+            [1, 4, 1, 10],
+        )
+        self.assertEqual(shape, [5, 4, 3, 10])
+
+        shape = paddle.broadcast_shapes([-1, 1, 3], [1, 6, 1], [1, 1, 3])
+        self.assertEqual(shape, [-1, 6, 3])
+
+        shape = paddle.broadcast_shapes([8, 3])
+
+        self.assertEqual(shape, [8, 3])
+
+        shape = paddle.broadcast_shapes([2, 3, 1], [6], [3, 1])
+        self.assertEqual(shape, [2, 3, 6])
+
+    def test_empty(self):
+        shape = paddle.broadcast_shapes([])
+        self.assertEqual(shape, [])
+
+        shape = paddle.broadcast_shapes([], [2, 3, 4])
+        self.assertEqual(shape, [2, 3, 4])
+
+        shape = paddle.broadcast_shapes([10, 1, 7], [], [1, 6, 1], [1, 1, 7])
+        self.assertEqual(shape, [10, 6, 7])
+
+    def test_complex_case(self):
+        test_cases = [
+            ([0], [1], [], [0]),
+            ([2, -1], [0], [2, 0]),
+            ([0, 3], [3], [0, 3]),
+            ([0, 1, 3], [0, 1, 0, 3], [1, 0, -1], [0, 0, 0, 3]),
+            ([0, 1, 3], [0, 1, 1, 5, 3], [], [0, 1, 0, 5, 3]),
+        ]
+
+        for shape_list in test_cases:
+            expected = shape_list[-1]
+            result = paddle.broadcast_shapes(*shape_list[:-1])
+            self.assertEqual(result, expected)
+
+    def test_error(self):
+        self.assertRaises(
+            ValueError, paddle.broadcast_shapes, [5, 1, 3], [1, 4, 1], [1, 2, 3]
+        )
+        self.assertRaises(ValueError, paddle.broadcast_shapes, [0], [0, 2])
+
+
+if __name__ == "__main__":
+    unittest.main()