mindspore 2.4.10__cp311-cp311-win_amd64.whl → 2.6.0rc1__cp311-cp311-win_amd64.whl

mindspore/hal/device.py

@@ -120,20 +120,21 @@ def _check_device_id(fn):
 
 def is_initialized(device_target):
     """
-    Returns whether specified backend is initialized.
+    Return whether specified device is initialized, this api will be deprecated and removed in future versions.
 
     Note:
-        MindSpore's backends "CPU", "GPU" and "Ascend" will be initialized in the following scenarios:
+        MindSpore's devices "CPU", "GPU" and "Ascend" will be initialized in the following scenarios:
 
-        - For distributed job, backend will be initialized after `mindspore.communication.init` method is called.
-        - For standalone job, backend will be initialized after running
+        - For distributed job, device will be initialized after `mindspore.communication.init` method is called.
+        - For standalone job, device will be initialized after running
           the first operator or calling creating stream/event interfaces.
 
     Args:
-        device_target (str): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str): The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` .
 
     Returns:
-        Bool, whether the specified backend is initialized.
+        bool
 
     Examples:
         >>> import mindspore as ms
@@ -159,19 +160,21 @@ def is_initialized(device_target):
 
 def is_available(device_target):
     """
-    Returns whether specified backend is available.
-    All dependent libraries should be successfully loaded if this backend is available.
+    Return whether specified device is available, this api will be deprecated and removed in future versions, please
+    use the api :func:`mindspore.device_context.cpu.is_available` , :func:`mindspore.device_context.gpu.is_available`,
+    :func:`mindspore.device_context.ascend.is_available` instead.
 
     Args:
-        device_target (str): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str): The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` . Default ``None`` , represents the current device set by context.
 
     Returns:
-        Bool, whether the specified backend is available for this MindSpore package.
+        bool
 
     Examples:
-        >>> import mindspore as ms
-        >>> device_target = ms.context.get_context("device_target")
-        >>> print(ms.hal.is_available(device_target))
+        >>> import mindspore
+        >>> device_target = mindspore.context.get_context("device_target")
+        >>> print(mindspore.hal.is_available(device_target))
         True
     """
     if device_target not in valid_targets:
@@ -192,22 +195,24 @@ def is_available(device_target):
 @_check_inputs_validation
 def device_count(device_target=None):
     """
-    Returns device count of specified backend.
+    Return device count of specified device, this api will be deprecated and removed in future versions, please use
+    the api :func:`mindspore.device_context.cpu.device_count` , :func:`mindspore.device_context.gpu.device_count`,
+    :func:`mindspore.device_context.ascend.device_count` instead.
 
     Note:
-        If `device_target` is not specified, get the device count of the current backend set by context.
-        For CPU backend, this method always returns 1.
+        For CPU device, this method always returns 1.
 
     Args:
-        device_target (str, optional): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str, optional): The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` . Default ``None`` , represents the current device set by context.
 
     Returns:
-        int.
+        int
 
     Examples:
-        >>> import mindspore as ms
-        >>> device_target = ms.context.get_context("device_target")
-        >>> print(ms.hal.device_count(device_target))
+        >>> import mindspore
+        >>> device_target = mindspore.context.get_context("device_target")
+        >>> print(mindspore.hal.device_count(device_target))
     """
     hal_instance = hal_instances.get(device_target)
     if hal_instance is None:
@@ -219,17 +224,15 @@ def device_count(device_target=None):
 @_check_inputs_validation
 def get_device_capability(device_id, device_target=None):
     """
-    Get specified device's capability.
-
-    Note:
-        If `device_target` is not specified, get the device capability of the current backend set by context.
+    Get specified device's capability, this api will be deprecated and removed in future versions.
 
     Args:
         device_id (int): The device id of which the capability will be returned.
-        device_target (str, optional): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str, optional):  The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` . Default ``None`` , represents the current device set by context.
 
     Returns:
-        tuple(int, int) for GPU.
+        tuple(param1, param2) for GPU.
 
         - param1 - int, cuda major revision number.
         - param2 - int, cuda minor revision number.
@@ -237,9 +240,9 @@ def get_device_capability(device_id, device_target=None):
         None for Ascend and CPU.
 
     Examples:
-        >>> import mindspore as ms
-        >>> device_target = ms.context.get_context("device_target")
-        >>> print(ms.hal.get_device_capability(0, device_target))
+        >>> import mindspore
+        >>> device_target = mindspore.context.get_context("device_target")
+        >>> print(mindspore.hal.get_device_capability(0, device_target))
     """
     hal_instance = hal_instances.get(device_target)
     if hal_instance is None:
@@ -251,17 +254,17 @@ def get_device_capability(device_id, device_target=None):
 @_check_inputs_validation
 def get_device_properties(device_id, device_target=None):
     """
-    Get specified device's properties.
+    Get specified device's properties, this api will be deprecated and removed in future versions.
 
     Note:
-        If `device_target` is not specified, get the device properties of the current backend set by context.
-        For Ascend, backend must be initialized before calling this method,
+        For Ascend, device must be initialized before calling this method,
         or `total_memory` and `free_memory` will be 0,
         and `device_id` will be ignored since this method only returns current device's properties.
 
     Args:
         device_id (int): The device id of which the properties will be returned.
-        device_target (str, optional): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str, optional): The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` . Default ``None`` , represents the current device set by context.
 
     Returns:
         - `cudaDeviceProp` for GPU.
@@ -292,9 +295,9 @@ def get_device_properties(device_id, device_target=None):
         - None for CPU.
 
     Examples:
-        >>> import mindspore as ms
-        >>> device_target = ms.context.get_context("device_target")
-        >>> print(ms.hal.get_device_properties(0, device_target))
+        >>> import mindspore
+        >>> device_target = mindspore.context.get_context("device_target")
+        >>> print(mindspore.hal.get_device_properties(0, device_target))
     """
     hal_instance = hal_instances.get(device_target)
     if hal_instance is None:
@@ -306,23 +309,23 @@ def get_device_properties(device_id, device_target=None):
 @_check_inputs_validation
 def get_device_name(device_id, device_target=None):
     """
-    Get specified device's name.
+    Get specified device's name, this api will be deprecated and removed in future versions.
 
     Note:
-        If `device_target` is not specified, get the device name of the current backend set by context.
-        This method always returns "CPU" for CPU backend.
+        This method always returns "CPU" for CPU device.
 
     Args:
         device_id (int): The device id of which the name will be returned.
-        device_target (str, optional): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str, optional): The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` . Default ``None`` , represents the current device set by context.
 
     Returns:
-        str.
+        str
 
     Examples:
-        >>> import mindspore as ms
-        >>> device_target = ms.context.get_context("device_target")
-        >>> print(ms.hal.get_device_name(0, device_target))
+        >>> import mindspore
+        >>> device_target = mindspore.context.get_context("device_target")
+        >>> print(mindspore.hal.get_device_name(0, device_target))
     """
     hal_instance = hal_instances.get(device_target)
     if hal_instance is None:
@@ -333,22 +336,21 @@ def get_device_name(device_id, device_target=None):
 @_check_inputs_validation
 def get_arch_list(device_target=None):
     """
-    Get the architecture list this MindSpore was compiled for.
-
-    Note:
-        If `device_target` is not specified, get the device name of the current backend set by context.
+    Get the architecture list this MindSpore was compiled for, this api will be deprecated and removed in future
+    versions.
 
     Args:
-        device_target (str, optional): The device name of backend, should be one of "CPU", "GPU" and "Ascend".
+        device_target (str, optional): The target device specified, should be one of ``"CPU"`` , ``"GPU"`` and
+            ``"Ascend"`` . Default ``None`` , represents the current device set by context.
 
     Returns:
         str for GPU.
         None for Ascend and CPU.
 
     Examples:
-        >>> import mindspore as ms
-        >>> device_target = ms.context.get_context("device_target")
-        >>> print(ms.hal.get_arch_list(device_target))
+        >>> import mindspore
+        >>> device_target = mindspore.context.get_context("device_target")
+        >>> print(mindspore.hal.get_arch_list(device_target))
     """
     hal_instance = hal_instances.get(device_target)
     if hal_instance is None:

mindspore/hal/event.py

@@ -17,11 +17,15 @@ from mindspore._c_expression import Event as Event_
 from mindspore._c_expression import Stream as Stream_
 from mindspore._c_expression import current_stream as current_stream_
 from mindspore import _checkparam as Validator
+from mindspore import log as logger
+
+function_event_status = {'Event': False, 'wait': False}
 
 
 class Event(Event_):
     r"""
-    Wrapper around a device event.
+    Wrapper around a device event, this api will be deprecated and removed in future versions, please use
+    the api :func:`mindspore.runtime.Event` instead.
 
     Device events are synchronization markers that can be used to monitor the device’s progress,
     to accurately measure timing, and to synchronize device streams.
@@ -29,36 +33,40 @@ class Event(Event_):
     The underlying device events are lazily initialized when the event is first recorded.
 
     Args:
-        enable_timing (bool, optional): indicates if the event should measure time (default: ``False``)
-        blocking (bool, optional): if ``True``, `wait` will be blocking (default: ``False``)
+        enable_timing (bool, optional): indicates if the event should measure time. Default ``False``.
+        blocking (bool, optional): if ``True``, `wait` will be blocking. Default ``False``.
 
     Examples:
-        >>> import mindspore as ms
-        >>> import numpy as np
-        >>> from mindspore import Tensor, ops
-        >>> start = ms.hal.Event(enable_timing=True)
-        >>> end = ms.hal.Event(enable_timing=True)
-        >>> s1 = ms.hal.Stream()
-        >>> s2 = ms.hal.Stream()
-        >>> a = Tensor(np.ones([2, 2]), ms.float32)
-        >>> b = Tensor(np.ones([2, 2]), ms.float32)
-        >>> c = Tensor(np.ones([2, 2]), ms.float32)
-        >>> with ms.hal.StreamCtx(s1):
-        ...     d = ops.matmul(a, b)
+        >>> import mindspore
+        >>> start = mindspore.hal.Event(enable_timing=True)
+        >>> end = mindspore.hal.Event(enable_timing=True)
+        >>> s1 = mindspore.hal.Stream()
+        >>> s2 = mindspore.hal.Stream()
+        >>> a = mindspore.tensor(mindspore.ops.ones([2, 2]), mindspore.float32)
+        >>> b = mindspore.tensor(mindspore.ops.ones([2, 2]), mindspore.float32)
+        >>> c = mindspore.tensor(mindspore.ops.ones([2, 2]), mindspore.float32)
+        >>> with mindspore.hal.StreamCtx(s1):
+        ...     d = mindspore.ops.matmul(a, b)
         ...     start.record()
         >>> c += 2
         >>> end.record()
-        >>> with ms.hal.StreamCtx(s2):
+        >>> with mindspore.hal.StreamCtx(s2):
         ...     start.synchronize()
         ...     end.synchronize()
         ...     e = c + d
-        >>> ms.hal.synchronize()
+        >>> mindspore.hal.synchronize()
         >>> print(e)
         [[5. 5.]
          [5. 5.]]
         >>> elapsed_time = start.elapsed_time(end)
     """
+
     def __init__(self, enable_timing=False, blocking=False):
+        if not function_event_status['Event']:
+            function_event_status['Event'] = True
+            logger.warning(
+                "WARN_DEPRECATED: The usage of mindspore.hal.Event(enable_timing=True) is deprecated."
+                " Please use mindspore.runtime.Event(enable_timing=True)")
         # pylint: disable=useless-super-delegation
         Validator.check_bool(enable_timing, "enable_timing", "Event")
         Validator.check_bool(blocking, "blocking", "Event")
@@ -66,17 +74,14 @@ class Event(Event_):
 
     def record(self, stream=None):
         r"""
-        Records the event in a given stream.
+        Record the event in a given stream.
 
         Uses :func:`mindspore.hal.current_stream()` if no `stream` is specified. The
         stream's device must match the event's device.
 
         Args:
             stream (Stream, optional): a stream to record. If this argument is ``None``,
-                current stream will be used. Default value: ``None``.
-
-        Raises:
-            TypeError: If 'stream' is neither a :class:`mindspore.hal.Stream` nor a ``None``.
+                current stream will be used. Default ``None``.
         """
         if stream is None:
             stream = current_stream_()
@@ -87,37 +92,37 @@ class Event(Event_):
 
     def wait(self, stream=None):
         r"""
-        Makes all future work submitted to the given stream wait for this
+        Make all future work submitted to the given stream wait for this
         event.
 
         Use :func:`mindspore.hal.current_stream()` if no `stream` is specified.
 
         Args:
             stream (Stream, optional): a stream to record. If this argument is ``None``,
-                current stream will be used. Default value: ``None``.
-
-        Raises:
-            TypeError: If 'stream' is neither a :class:`mindspore.hal.Stream` nor a ``None``.
+                current stream will be used. Default ``None``.
 
         Examples:
-            >>> import mindspore as ms
-            >>> import numpy as np
-            >>> from mindspore import Tensor, ops
-            >>> event = ms.hal.Event()
-            >>> s1 = ms.hal.Stream()
-            >>> s2 = ms.hal.Stream()
-            >>> a = Tensor(np.ones([2, 2]), ms.float32)
-            >>> b = Tensor(np.ones([2, 2]), ms.float32)
-            >>> with ms.hal.StreamCtx(s1):
-            ...     c = ops.matmul(a, b)
+            >>> import mindspore
+            >>> event = mindspore.hal.Event()
+            >>> s1 = mindspore.hal.Stream()
+            >>> s2 = mindspore.hal.Stream()
+            >>> a = mindspore.tensor(mindspore.ops.ones([2, 2]), mindspore.float32)
+            >>> b = mindspore.tensor(mindspore.ops.ones([2, 2]), mindspore.float32)
+            >>> with mindspore.hal.StreamCtx(s1):
+            ...     c = mindspore.ops.matmul(a, b)
             ...     event.record()
             >>> event.wait()
             >>> d = c + 2
-            >>> ms.hal.synchronize()
+            >>> mindspore.hal.synchronize()
             >>> print(d)
             [[4. 4.]
              [4. 4.]]
         """
+        if not function_event_status['wait']:
+            function_event_status['wait'] = True
+            logger.warning(
+                "WARN_DEPRECATED: The usage of mindspore.hal.Event() is deprecated."
+                " Please use mindspore.runtime.Event()")
         if stream is None:
             stream = current_stream_()
         if not isinstance(stream, Stream_):
@@ -127,7 +132,7 @@ class Event(Event_):
 
     def synchronize(self):
         r"""
-        Waits for the event to complete.
+        Wait for the event to complete.
 
         Waits until the completion of all work currently captured in this event.
         This prevents the CPU thread from proceeding until the event completes.
@@ -137,20 +142,18 @@ class Event(Event_):
 
     def query(self):
         r"""
-        Checks if all work currently captured by event has completed.
+        Check if all work currently captured by event has completed.
 
         Returns:
             A boolean indicating if all work currently captured by event has completed.
 
         Examples:
-            >>> import mindspore as ms
-            >>> import numpy as np
-            >>> from mindspore import Tensor, ops
-            >>> a = Tensor(np.ones([1024, 2048]), ms.float32)
-            >>> b = Tensor(np.ones([2048, 4096]), ms.float32)
-            >>> s1 = ms.hal.Stream()
-            >>> with ms.hal.StreamCtx(s1):
-            ...     c = ops.matmul(a, b)
+            >>> import mindspore
+            >>> a = mindspore.tensor(mindspore.ops.ones([1024, 2048]), mindspore.float32)
+            >>> b = mindspore.tensor(mindspore.ops.ones([2048, 4096]), mindspore.float32)
+            >>> s1 = mindspore.hal.Stream()
+            >>> with mindspore.hal.StreamCtx(s1):
+            ...     c = mindspore.ops.matmul(a, b)
             ...     ev = s1.record_event()
             >>> s1.synchronize()
             >>> assert ev.query()
@@ -160,7 +163,7 @@ class Event(Event_):
 
     def elapsed_time(self, end_event):
         r"""
-        Returns the time elapsed in milliseconds after the event was
+        Return the time elapsed in milliseconds after the event was
         recorded and before the end_event was recorded.
 
         Args:
@@ -168,9 +171,6 @@ class Event(Event_):
 
         Returns:
             float, the time elapsed in milliseconds.
-
-        Raises:
-            TypeError: If 'end_event' is not a :class:`mindspore.hal.Event`.
         """
         # pylint: disable=useless-super-delegation
         if not isinstance(end_event, Event):