From e9584205dfe6a1f68c083906db35b9691a63d93d Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:30:01 -0500 Subject: [PATCH 01/31] Docstring edit for intel_device_info function --- dpctl/utils/__init__.py | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/dpctl/utils/__init__.py b/dpctl/utils/__init__.py index 0dbcefd596..50dac796e5 100644 --- a/dpctl/utils/__init__.py +++ b/dpctl/utils/__init__.py @@ -46,18 +46,27 @@ def intel_device_info(dev): dictionary otherwise. The dictionary contains the following keys: - device_id: 32-bits device PCI identifier - gpu_eu_count: Total number of execution units - gpu_hw_threads_per_eu: Number of thread contexts in EU - gpu_eu_simd_width: Physical SIMD width of EU - gpu_slices: Total number of slices - gpu_subslices_per_slice: Number of sub-slices per slice - gpu_eu_count_per_subslice: Number of EUs in subslice - max_mem_bandwidth: Maximum memory bandwidth in bytes/second + device_id: + 32-bits device PCI identifier + gpu_eu_count: + Total number of execution units + gpu_hw_threads_per_eu: + Number of thread contexts in EU + gpu_eu_simd_width: + Physical SIMD width of EU + gpu_slices: + Total number of slices + gpu_subslices_per_slice: + Number of sub-slices per slice + gpu_eu_count_per_subslice: + Number of EUs in subslice + max_mem_bandwidth: + Maximum memory bandwidth in bytes/second Unsupported descriptors are omitted from the dictionary. - Descriptors other than PCI identifier are supported only for - SyclDevices with Leve-Zero backend. + + Descriptors other than the PCI identifier are supported only + for :class:`.SyclDevices` with Leve-Zero backend. """ if not isinstance(dev, SyclDevice): raise TypeError(f"Expected dpctl.SyclDevice, got {type(dev)}") From b817b942eeae2c962bd48596433fe6f4861ebe19 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:30:53 -0500 Subject: [PATCH 02/31] Docstring edits for SyclContext --- dpctl/_sycl_context.pyx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/dpctl/_sycl_context.pyx b/dpctl/_sycl_context.pyx index 35290e5888..87e7d6aaf2 100644 --- a/dpctl/_sycl_context.pyx +++ b/dpctl/_sycl_context.pyx @@ -60,9 +60,8 @@ _logger = logging.getLogger(__name__) cdef class SyclContextCreationError(Exception): """ - A SyclContextCreationError exception is raised when - SyclContext could not created. - + A ``SyclContextCreationError`` exception is raised + when :class:`.SyclContext` could not created. """ pass @@ -97,7 +96,7 @@ cdef class _SyclContext: cdef class SyclContext(_SyclContext): """ SyclContext(arg=None) - A Python wrapper for the :sycl_context:`sycl::context <>` C++ class. + A Python wrapper for the ``sycl::context`` C++ class. There are multiple ways to create a :class:`dpctl.SyclContext` object: @@ -109,7 +108,7 @@ cdef class SyclContext(_SyclContext): import dpctl - # Create a default SyclContext + # Create a SyclContext for default-selected device ctx = dpctl.SyclContext() print(ctx.get_devices()) From add054e2bf8585445143abe1b821ed8c914d3051 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:31:30 -0500 Subject: [PATCH 03/31] Docstring edits for SyclDevice and exceptions --- dpctl/_sycl_device.pyx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index 9388c1c69b..a35c6e250b 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -122,25 +122,26 @@ __all__ = [ cdef class SyclDeviceCreationError(Exception): """ - A SyclDeviceCreationError exception is raised when - SyclDevice instance could not created. - + A ``SyclDeviceCreationError`` exception is raised when + :class:`.SyclDevice` instance could not created. """ pass cdef class SyclSubDeviceCreationError(Exception): """ - A SyclSubDeviceCreationError exception is raised when - sub-devices were not created. - + A ``SyclSubDeviceCreationError`` exception is raised + by :meth:`.SyclDevice.create_sub_devices` when + :class:`.SyclDevice` instance could not be partitioned + into sub-devices. """ pass cdef class _SyclDevice: """ - A helper data-owner class to abstract a `sycl::device` instance. + A helper data-owner class to abstract ``sycl::device`` + instance. """ def __dealloc__(self): @@ -234,7 +235,7 @@ def _cached_filter_string(d : SyclDevice): cdef class SyclDevice(_SyclDevice): """ SyclDevice(arg=None) - A Python wrapper for the :sycl_device:`sycl::device <>` C++ class. + A Python wrapper for the ``sycl::device`` C++ class. There are two ways of creating a SyclDevice instance: @@ -254,10 +255,10 @@ cdef class SyclDevice(_SyclDevice): - by calling one of the device selector helper functions: - :func:`dpctl.select_accelerator_device()`, - :func:`dpctl.select_cpu_device()`, - :func:`dpctl.select_default_device()`, - :func:`dpctl.select_gpu_device()`, + :py:func:`dpctl.select_accelerator_device()`, + :py:func:`dpctl.select_cpu_device()`, + :py:func:`dpctl.select_default_device()`, + :py:func:`dpctl.select_gpu_device()`, :Example: @@ -283,7 +284,6 @@ cdef class SyclDevice(_SyclDevice): or the input capsule contained a null pointer or could not be renamed. - """ @staticmethod cdef SyclDevice _create(DPCTLSyclDeviceRef dref): From 729dcb915c06d4389c0c9cea62af1069b815f03d Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:32:17 -0500 Subject: [PATCH 04/31] Docstring edits for device selection free functions --- dpctl/_sycl_device_factory.pyx | 89 +++++++++++++++++++++------------- 1 file changed, 54 insertions(+), 35 deletions(-) diff --git a/dpctl/_sycl_device_factory.pyx b/dpctl/_sycl_device_factory.pyx index 80a64136d9..1d4adc574f 100644 --- a/dpctl/_sycl_device_factory.pyx +++ b/dpctl/_sycl_device_factory.pyx @@ -141,7 +141,7 @@ cdef list _get_devices(DPCTLDeviceVectorRef DVRef): cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all): - """ get_devices(backend=backend_type.all, device_type=device_type_t.all) + """ Returns a list of :class:`dpctl.SyclDevice` instances selected based on the given :class:`dpctl.device_type` and :class:`dpctl.backend_type` values. @@ -150,18 +150,21 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all): ``backend`` in addition to only ``device_type``. Args: - backend (optional): Defaults to ``dpctl.backend_type.all``. + backend (optional): A :class:`dpctl.backend_type` enum value or a string that specifies a SYCL backend. Currently, accepted values are: "cuda", "opencl", "level_zero", or "all". - device_type (optional): Defaults to ``dpctl.device_type.all``. + Default: ``dpctl.backend_type.all``. + device_type (optional): A :class:`dpctl.device_type` enum value or a string that specifies a SYCL device type. Currently, accepted values are: "gpu", "cpu", "accelerator", "host", or "all". + Default: ``dpctl.device_type.all``. Returns: - list: A list of available :class:`dpctl.SyclDevice` instances that - satisfy the provided :class:`dpctl.backend_type` and - :class:`dpctl.device_type` values. + list: + A list of available :class:`dpctl.SyclDevice` instances that + satisfy the provided :class:`dpctl.backend_type` and + :class:`dpctl.device_type` values. """ cdef _backend_type BTy = _backend_type._ALL_BACKENDS cdef _device_type DTy = _device_type._ALL_DEVICES @@ -198,22 +201,26 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all): cpdef int get_num_devices( backend=backend_type.all, device_type=device_type_t.all ): - """ get_num_devices(backend=backend_type.all, device_type=device_type_t.all) + """ A helper function to return the number of SYCL devices of a given :class:`dpctl.device_type` and :class:`dpctl.backend_type`. Args: - backend (optional): Defaults to ``dpctl.backend_type.all``. + backend (optional): A :class:`dpctl.backend_type` enum value or a string that specifies a SYCL backend. Currently, accepted values are: "cuda", "opencl", "level_zero", or "all". - device_type (optional): Defaults to ``dpctl.device_type.all``. + Default: ``dpctl.backend_type.all``. + device_type (optional): A :class:`dpctl.device_type` enum value or a string that specifies a SYCL device type. Currently, accepted values are: "gpu", "cpu", "accelerator", "host", or "all". + Default: ``dpctl.device_type.all``. Returns: - int: The number of available SYCL devices that satisfy the provided - :class:`dpctl.backend_type` and :class:`dpctl.device_type` values. + int: + The number of available SYCL devices that satisfy the provided + :py:class:`dpctl.backend_type` and :py:class:`dpctl.device_type` + values. """ cdef _backend_type BTy = _backend_type._ALL_BACKENDS cdef _device_type DTy = _device_type._ALL_DEVICES @@ -248,8 +255,9 @@ cpdef cpp_bool has_cpu_devices(): """ A helper function to check if there are any SYCL CPU devices available. Returns: - bool: ``True`` if ``sycl::device_type::cpu`` devices are present, - ``False`` otherwise. + bool: + ``True`` if ``sycl::device_type::cpu`` devices are present, + ``False`` otherwise. """ cdef int num_cpu_dev = DPCTLDeviceMgr_GetNumDevices(_device_type._CPU) return num_cpu_dev @@ -259,8 +267,9 @@ cpdef cpp_bool has_gpu_devices(): """ A helper function to check if there are any SYCL GPU devices available. Returns: - bool: ``True`` if ``sycl::device_type::gpu`` devices are present, - ``False`` otherwise. + bool: + ``True`` if ``sycl::device_type::gpu`` devices are present, + ``False`` otherwise. """ cdef int num_gpu_dev = DPCTLDeviceMgr_GetNumDevices(_device_type._GPU) return num_gpu_dev @@ -271,8 +280,9 @@ cpdef cpp_bool has_accelerator_devices(): available. Returns: - bool: ``True`` if ``sycl::device_type::accelerator`` devices are - present, ``False`` otherwise. + bool: + ``True`` if ``sycl::device_type::accelerator`` devices are + present, ``False`` otherwise. """ cdef int num_accelerator_dev = DPCTLDeviceMgr_GetNumDevices( _device_type._ACCELERATOR @@ -284,11 +294,13 @@ cpdef SyclDevice select_accelerator_device(): """ A wrapper for SYCL's ``accelerator_selector`` class. Returns: - dpctl.SyclDevice: A Python object wrapping the SYCL ``device`` - returned by the SYCL ``accelerator_selector``. + dpctl.SyclDevice: + A Python object wrapping the SYCL ``device`` + returned by the SYCL ``accelerator_selector``. Raises: - dpctl.SyclDeviceCreatioError: If the SYCL ``accelerator_selector`` is - unable to select a ``device``. + dpctl.SyclDeviceCreationError: + If the SYCL ``accelerator_selector`` is + unable to select a ``device``. """ cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLAcceleratorSelector_Create() cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef) @@ -304,11 +316,13 @@ cpdef SyclDevice select_cpu_device(): """ A wrapper for SYCL's ``cpu_selector`` class. Returns: - dpctl.SyclDevice: A Python object wrapping the SYCL ``device`` - returned by the SYCL ``cpu_selector``. + dpctl.SyclDevice: + A Python object wrapping the SYCL ``device`` + returned by the SYCL ``cpu_selector``. Raises: - dpctl.SyclDeviceCreationError: If the SYCL ``cpu_selector`` is - unable to select a ``device``. + dpctl.SyclDeviceCreationError: + If the SYCL ``cpu_selector`` is + unable to select a ``device``. """ cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLCPUSelector_Create() cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef) @@ -324,11 +338,13 @@ cpdef SyclDevice select_default_device(): """ A wrapper for SYCL's ``default_selector`` class. Returns: - dpctl.SyclDevice: A Python object wrapping the SYCL ``device`` - returned by the SYCL ``default_selector``. + dpctl.SyclDevice: + A Python object wrapping the SYCL ``device`` + returned by the SYCL ``default_selector``. Raises: - dpctl.SyclDeviceCreationError: If the SYCL ``default_selector`` is - unable to select a ``device``. + dpctl.SyclDeviceCreationError: + If the SYCL ``default_selector`` is + unable to select a ``device``. """ cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLDefaultSelector_Create() cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef) @@ -344,11 +360,13 @@ cpdef SyclDevice select_gpu_device(): """ A wrapper for SYCL's ``gpu_selector`` class. Returns: - dpctl.SyclDevice: A Python object wrapping the SYCL ``device`` - returned by the SYCL ``gpu_selector``. + dpctl.SyclDevice: + A Python object wrapping the SYCL ``device`` + returned by the SYCL ``gpu_selector``. Raises: - dpctl.SyclDeviceCreationError: If the SYCL ``gpu_selector`` is - unable to select a ``device``. + dpctl.SyclDeviceCreationError: + If the SYCL ``gpu_selector`` is + unable to select a ``device``. """ cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLGPUSelector_Create() cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef) @@ -393,10 +411,11 @@ _global_default_device_cache = ContextVar( cpdef SyclDevice _cached_default_device(): - """Returns a cached devide selected by default selector. + """Returns a cached device selected by default selector. Returns: - :class:`dpctl.SyclDevice`: A cached default-selected SYCL device. + dpctl.SyclDevice: + A cached default-selected SYCL device. """ cdef _DefaultDeviceCache _cache = _global_default_device_cache.get() From 43798482308c631f83b99fddd219c7d8d7e249a8 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:32:55 -0500 Subject: [PATCH 05/31] Docstring edits for SyclPlatform class and lsplatform function --- dpctl/_sycl_platform.pyx | 47 ++++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/dpctl/_sycl_platform.pyx b/dpctl/_sycl_platform.pyx index a99add4667..a18c2764cd 100644 --- a/dpctl/_sycl_platform.pyx +++ b/dpctl/_sycl_platform.pyx @@ -85,12 +85,36 @@ cdef void _init_helper(_SyclPlatform platform, DPCTLSyclPlatformRef PRef): cdef class SyclPlatform(_SyclPlatform): """ SyclPlatform(self, arg=None) - Python class representing ``sycl::platform`` class. + Python class representing ``sycl::platform`` class. - SyclPlatform() - create platform selected by sycl::default_selector - SyclPlatform(filter_selector) - create platform selected by filter - selector + There are two ways of creating a SyclDevice instance: + + - Invoking the constructor with no arguments creates a + platform using the default selector. + + :Example: + .. code-block:: python + + import dpctl + + # Create a SyclPlatform for default-selected device + pl = dpctl.SyclPlatform() + print(pl.name, pl.version) + + - Invoking the constructor with specific filter selector string that + creates a queue for the device corresponding to the filter string. + + :Example: + .. code-block:: python + + import dpctl + + # Create a SyclPlatform for device selected by + # filter-selector string + pl = dpctl.SyclPlatform("opencl:cpu") + print(pl.name, pl.version) """ + @staticmethod cdef SyclPlatform _create(DPCTLSyclPlatformRef pref): """ @@ -340,11 +364,16 @@ def lsplatform(verbosity=0): :Example: On a system with an OpenCL CPU driver, OpenCL GPU driver, - Level Zero GPU driver, running the command. :: + Level Zero GPU driver, running the command: + + .. code-block:: bash + + $ python -c "import dpctl; dpctl.lsplatform(verbosity=2)" - $ python -c "import dpctl; dpctl.lsplatform()" + outputs - returns :: + .. code-block:: text + :caption: Sample output of lsplatform(verbosity=2) Platform 0:: Name Intel(R) OpenCL @@ -381,10 +410,10 @@ def lsplatform(verbosity=0): Device type gpu Args: - verbosity (optional): Defaults to 0. + verbosity (Literal[0,1,2], optional): The verbosity controls how much information is printed by the function. 0 is the lowest level set by default and 2 is the highest - level to print the most verbose output. + level to print the most verbose output. Default: `0`. """ cdef DPCTLPlatformVectorRef PVRef = NULL cdef size_t v = 0 From bd1f303b0df6ca43939227238ecf28de09de2d30 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:33:32 -0500 Subject: [PATCH 06/31] Docstring edits for SyclQueue and exceptions --- dpctl/_sycl_queue.pyx | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/dpctl/_sycl_queue.pyx b/dpctl/_sycl_queue.pyx index 75135c6fc6..5204a59f9b 100644 --- a/dpctl/_sycl_queue.pyx +++ b/dpctl/_sycl_queue.pyx @@ -248,8 +248,9 @@ kernel_arg_type = _kernel_arg_type() cdef class SyclKernelSubmitError(Exception): """ - A SyclKernelSubmitError exception is raised when the provided - :class:`.SyclKernel` could not be submitted to the :class:`.SyclQueue`. + A ``SyclKernelSubmitError`` exception is raised when + the provided :class:`.program.SyclKernel` could not be + submitted to the :class:`.SyclQueue`. """ pass @@ -257,16 +258,18 @@ cdef class SyclKernelSubmitError(Exception): cdef class SyclKernelInvalidRangeError(Exception): """ - A SyclKernelInvalidRangeError is raised when the provided range has less - than one or more than three dimensions. + A ``SyclKernelInvalidRangeError`` is raised when the provided + range has less than one or more than three dimensions. """ pass cdef class SyclQueueCreationError(Exception): """ - A SyclQueueCreationError exception is raised when a :class:`.SyclQueue` - could not be created. :class:`.SyclQueue` creation can fail if the filter + A ``SyclQueueCreationError`` exception is raised when a + :class:`.SyclQueue` could not be created. + + :class:`.SyclQueue` creation can fail if the filter string is invalid, or the backend or device type values are not supported. """ @@ -389,8 +392,9 @@ cdef class _SyclQueue: cdef class SyclQueue(_SyclQueue): """ SyclQueue(*args, **kwargs) - Python class representing ``sycl::queue``. There are multiple - ways to create a :class:`dpctl.SyclQueue` object: + Python class representing ``sycl::queue``. + + There are multiple ways to create a :class:`dpctl.SyclQueue` object: - Invoking the constructor with no arguments creates a context using the default selector. From 699bb785d668a6a727cb5da3b98b9d8858d4b37d Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:34:11 -0500 Subject: [PATCH 07/31] Docstring edits for SyclTimer class --- dpctl/_sycl_timer.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/dpctl/_sycl_timer.py b/dpctl/_sycl_timer.py index db705f8572..9f31d3c45a 100644 --- a/dpctl/_sycl_timer.py +++ b/dpctl/_sycl_timer.py @@ -46,9 +46,8 @@ def device_dt(self): class SyclTimer: """ - SyclTimer(host_timer=timeit.default_timer, time_scale=1) - Python class to measure device time of execution of commands submitted to - :class:`dpctl.SyclQueue` as well as the wall-time. + Context to measure device time and host wall-time of execution + of commands submitted to :class:`dpctl.SyclQueue`. :Example: .. code-block:: python @@ -79,10 +78,13 @@ class SyclTimer: execution and thus effectively synchronizes the queue. Args: - host_timer (callable): A callable such that host_timer() returns current + host_timer (callable, optional): + A callable such that host_timer() returns current host time in seconds. - time_scale (int, float): Ratio of the unit of time of interest and - one second. + Default: :py:func:`timeit.default_timer`. + time_scale (Union[int, float], optional): + Ratio of the unit of time of interest and one second. + Default: `1`. """ def __init__(self, host_timer=timeit.default_timer, time_scale=1): From 4a6dd7484352a4ceafca4478bed6aba9f267f6a7 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:35:33 -0500 Subject: [PATCH 08/31] Docstring edit for docstring of usm_ndarray A new line was added after table of enumerations of supported dtype keyword values to make sphinx happy. --- dpctl/tensor/_usmarray.pyx | 1 + 1 file changed, 1 insertion(+) diff --git a/dpctl/tensor/_usmarray.pyx b/dpctl/tensor/_usmarray.pyx index b018430f03..e98acbc3cf 100644 --- a/dpctl/tensor/_usmarray.pyx +++ b/dpctl/tensor/_usmarray.pyx @@ -99,6 +99,7 @@ cdef class usm_ndarray: double-precision real and complex floating types, supported if target device's property ``has_aspect_fp64`` is ``True``. + Default: ``None``. strides (tuple, optional): Strides of the array to be created in elements. From a3691a21bd1c9810e55ee287af25f76dd0721304 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 09:36:41 -0500 Subject: [PATCH 09/31] Docstring edits for tensor.can_cast function --- dpctl/tensor/_type_utils.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dpctl/tensor/_type_utils.py b/dpctl/tensor/_type_utils.py index 005e452219..fd5f09392b 100644 --- a/dpctl/tensor/_type_utils.py +++ b/dpctl/tensor/_type_utils.py @@ -487,7 +487,7 @@ def __repr__(self): return self._finfo.__repr__() -def can_cast(from_, to, casting="safe"): +def can_cast(from_, to, casting="safe") -> bool: """ can_cast(from, to, casting="safe") Determines if one data type can be cast to another data type according \ @@ -501,11 +501,13 @@ def can_cast(from_, to, casting="safe"): target data type casting (Optional[str]): controls what kind of data casting may occur. + * "no" means data types should not be cast at all. * "safe" means only casts that preserve values are allowed. * "same_kind" means only safe casts and casts within a kind, like `float64` to `float32`, are allowed. * "unsafe" means any data conversion can be done. + Default: `"safe"`. Returns: From d23808060b446a927ad569b16551b44c223ceb7f Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 11:00:27 -0500 Subject: [PATCH 10/31] Docstring edits in creation/elementwise functions Added delimiters for positional/only, keyword/only, or positional-or-keyword arguments of array creation and elementwise functions. Modified implementation code and tests to specify arguments as keyword argument that had become keyword-only per array API specification. --- dpctl/tensor/_copy_utils.py | 2 +- dpctl/tensor/_ctors.py | 110 ++- dpctl/tensor/_elementwise_common.py | 4 +- dpctl/tensor/_elementwise_funcs.py | 775 +++++++++++------- dpctl/tensor/_manipulation_functions.py | 9 +- dpctl/tensor/_statistical_functions.py | 4 +- dpctl/tests/elementwise/test_add.py | 50 +- dpctl/tests/elementwise/test_equal.py | 2 +- .../elementwise/test_floor_ceil_trunc.py | 13 +- dpctl/tests/elementwise/test_hyperbolic.py | 9 +- dpctl/tests/elementwise/test_logaddexp.py | 14 +- dpctl/tests/elementwise/test_not_equal.py | 2 +- dpctl/tests/elementwise/test_trigonometric.py | 9 +- dpctl/tests/test_usm_ndarray_ctor.py | 20 +- dpctl/tests/test_usm_ndarray_indexing.py | 2 +- dpctl/tests/test_usm_ndarray_manipulation.py | 6 +- 16 files changed, 614 insertions(+), 417 deletions(-) diff --git a/dpctl/tensor/_copy_utils.py b/dpctl/tensor/_copy_utils.py index 10b1f30fca..5ddb8c1a87 100644 --- a/dpctl/tensor/_copy_utils.py +++ b/dpctl/tensor/_copy_utils.py @@ -900,7 +900,7 @@ def _put_multi_index(ary, inds, p, vals): vals_usm_type = dpctl.utils.get_coerced_usm_type(usm_types_) if not isinstance(vals, dpt.usm_ndarray): vals = dpt.asarray( - vals, ary.dtype, usm_type=vals_usm_type, sycl_queue=exec_q + vals, dtype=ary.dtype, usm_type=vals_usm_type, sycl_queue=exec_q ) vals = dpt.broadcast_to(vals, vals_shape) diff --git a/dpctl/tensor/_ctors.py b/dpctl/tensor/_ctors.py index aec545397d..d33615ca0a 100644 --- a/dpctl/tensor/_ctors.py +++ b/dpctl/tensor/_ctors.py @@ -264,14 +264,15 @@ def _ensure_native_dtype_device_support(dtype, dev) -> None: """Check that dtype is natively supported by device. Arg: - dtype: - Elemental data-type - dev (:class:`dpctl.SyclDevice`): - The device about which the query is being made. + dtype: + Elemental data-type + dev (:class:`dpctl.SyclDevice`): + The device about which the query is being made. Returns: - None + None Raise: - ValueError - if device does not natively support this dtype. + ValueError: + if device does not natively support this `dtype`. """ if dtype in [dpt.float64, dpt.complex128] and not dev.has_aspect_fp64: raise ValueError( @@ -384,7 +385,7 @@ def _asarray_from_seq( usm_type=None, order="C", ): - "`obj` is a sequence" + "`seq_obj` is a sequence" if usm_type is None: usm_types_in_seq = [] _usm_types_walker(seq_obj, usm_types_in_seq) @@ -461,6 +462,8 @@ def _asarray_from_seq_single_device( def asarray( obj, + /, + *, dtype=None, device=None, copy=None, @@ -468,10 +471,8 @@ def asarray( sycl_queue=None, order="K", ): - """ asarray(obj, dtype=None, copy=None, device=None, \ - usm_type=None, sycl_queue=None, order="K") - - Converts `obj` to :class:`dpctl.tensor.usm_ndarray`. + """ + Converts input object to :class:`dpctl.tensor.usm_ndarray`. Args: obj: Python object to convert. Can be an instance of @@ -497,7 +498,7 @@ def asarray( non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. For `usm_type=None` the allocation type is inferred from the input if `obj` has USM allocation, or `"device"` is used instead. Default: `None`. @@ -649,15 +650,14 @@ def asarray( def empty( shape, + *, dtype=None, order="C", device=None, usm_type="device", sycl_queue=None, ): - """ empty(shape, dtype=None, order="C", device=None, \ - usm_type="device", sycl_queue=None) - + """ Creates :class:`dpctl.tensor.usm_ndarray` from uninitialized USM allocation. @@ -674,7 +674,7 @@ def empty( non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. Default: `"device"`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` @@ -762,9 +762,7 @@ def arange( usm_type="device", sycl_queue=None, ): - """ arange(start, /, stop=None, step=1, *, dtype=None, \ - device=None, usm_type="device", sycl_queue=None) - + """ Returns evenly spaced values within the half-open interval [start, stop) as a one-dimensional array. @@ -779,7 +777,7 @@ def arange( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. Default: `'device'`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` @@ -856,15 +854,14 @@ def arange( def zeros( shape, + *, dtype=None, order="C", device=None, usm_type="device", sycl_queue=None, ): - """ zeros(shape, dtype=None, order="C", device=None, \ - usm_type="device", sycl_queue=None) - + """ Returns a new :class:`dpctl.tensor.usm_ndarray` having a specified shape and filled with zeros. @@ -880,7 +877,7 @@ def zeros( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. Default: `"device"`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` @@ -916,6 +913,7 @@ def zeros( def ones( shape, + *, dtype=None, order="C", device=None, @@ -940,7 +938,7 @@ def ones( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. Default: `"device"`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` @@ -977,15 +975,14 @@ def ones( def full( shape, fill_value, + *, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None, ): - """ full(shape, fill_value, dtype=None, order="C", \ - device=None, usm_type=None, sycl_queue=None) - + """ Returns a new :class:`dpctl.tensor.usm_ndarray` having a specified shape and filled with `fill_value`. @@ -1002,7 +999,7 @@ def full( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host"|None, optional): The type of SYCL + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. If `usm_type` is `None`, it is inferred from `fill_value` input if it is an instance of `ums_ndarray`, or interpreted as `"device"` otherwise. @@ -1070,11 +1067,9 @@ def full( def empty_like( - x, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None + x, /, *, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None ): - """ empty_like(x, dtype=None, order="C", \ - device=None, usm_type=None, sycl_queue=None) - + """ Returns an uninitialized :class:`dpctl.tensor.usm_ndarray` with the same `shape` as the input array `x`. @@ -1082,18 +1077,18 @@ def empty_like( x (usm_ndarray): Input array from which to derive the output array shape. dtype (optional): data type of the array. Can be typestring, - a `numpy.dtype` object, `numpy` char string, or a numpy - scalar type. Default: `None`. - order ("C", or F"): memory layout for the array. Default: `"C"` + a :py:class:`numpy.dtype` object, numpy char string, + or a numpy scalar type. Default: `None`. + order ("C" or F"): memory layout for the array. Default: `"C"`. device (optional): array API concept of device where the output array is created. `device` can be `None`, a oneAPI filter selector string, an instance of :class:`dpctl.SyclDevice` corresponding to a non-partitioned SYCL device, an instance of - :class:`dpctl.SyclQueue`, or a `Device` object returned by - :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host"|None, optional): The type of SYCL + :py:class:`dpctl.SyclQueue`, or a `Device` object returned by + :py:attr:`dpctl.tensor.usm_array.device`. Default: `None`. + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. If `usm_type` is `None`, the - the `usm_type` is inferred from the input array. Default: `None`. + the ``usm_type`` is inferred from the input array. Default: `None`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` are exclusive keywords, i.e. use one or another. If both are @@ -1135,11 +1130,9 @@ def empty_like( def zeros_like( - x, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None + x, /, *, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None ): - """ zeros_like(x, dtype=None, order="C", \ - device=None, usm_type=None, sycl_queue=None) - + """ Creates :class:`dpctl.tensor.usm_ndarray` from USM allocation initialized with zeros. @@ -1157,7 +1150,7 @@ def zeros_like( to a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host"|None, optional): The type of SYCL + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. If `None`, output array has the same USM allocation type as the input array. Default: `None`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use @@ -1200,11 +1193,9 @@ def zeros_like( def ones_like( - x, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None + x, /, *, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None ): - """ ones_like(x, dtype=None, order="C", \ - device=None, usm_type=None, sycl_queue=None) - + """ Returns a new :class:`dpctl.tensor.usm_ndarray` filled with ones and having the same `shape` as the input array `x`. @@ -1221,7 +1212,7 @@ def ones_like( to a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host"|None, optional): The type of SYCL + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. If `None`, output array has the same USM allocation type as the input array. Default: `None`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use @@ -1265,7 +1256,9 @@ def ones_like( def full_like( x, + /, fill_value, + *, dtype=None, order="C", device=None, @@ -1293,7 +1286,7 @@ def full_like( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host"|None, optional): The type of SYCL + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. If `None`, output array has the same USM allocation type as the input array `x`. Default: `None`. @@ -1377,7 +1370,7 @@ def linspace( non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. Default: `"device"`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` @@ -1463,7 +1456,7 @@ def eye( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :attr:`dpctl.tensor.usm_array.device`. Default: `None`. - usm_type ("device"|"shared"|"host", optional): The type of SYCL USM + usm_type ("device", "shared", "host", optional): The type of SYCL USM allocation for the output array. Default: `"device"`. sycl_queue (:class:`dpctl.SyclQueue`, optional): The SYCL queue to use for output array allocation and copying. `sycl_queue` and `device` @@ -1511,10 +1504,8 @@ def eye( return res -def tril(x, k=0): +def tril(x, /, *, k=0): """ - tril(x, k=0) - Returns the lower triangular part of a matrix (or a stack of matrices) `x`. The lower triangular part of the matrix is defined as the elements on and @@ -1581,10 +1572,8 @@ def tril(x, k=0): return res -def triu(x, k=0): +def triu(x, /, *, k=0): """ - triu(x, k=0) - Returns the upper triangular part of a matrix (or a stack of matrices) `x`. The upper triangular part of the matrix is defined as the elements on and @@ -1652,8 +1641,7 @@ def triu(x, k=0): def meshgrid(*arrays, indexing="xy"): - """meshgrid(*arrays, indexing="xy") - + """ Creates list of :class:`dpctl.tensor.usm_ndarray` coordinate matrices from vectors. diff --git a/dpctl/tensor/_elementwise_common.py b/dpctl/tensor/_elementwise_common.py index 89f10321db..fbfe22410d 100644 --- a/dpctl/tensor/_elementwise_common.py +++ b/dpctl/tensor/_elementwise_common.py @@ -175,7 +175,7 @@ def types(self): self.types_ = types return types - def __call__(self, x, out=None, order="K"): + def __call__(self, x, /, *, out=None, order="K"): if not isinstance(x, dpt.usm_ndarray): raise TypeError(f"Expected dpctl.tensor.usm_ndarray, got {type(x)}") @@ -515,7 +515,7 @@ def types(self): self.types_ = types return types - def __call__(self, o1, o2, out=None, order="K"): + def __call__(self, o1, o2, /, *, out=None, order="K"): if order not in ["K", "C", "F", "A"]: order = "K" q1, o1_usm_type = _get_queue_usm_type(o1) diff --git a/dpctl/tensor/_elementwise_funcs.py b/dpctl/tensor/_elementwise_funcs.py index 98c92c5807..526fb25462 100644 --- a/dpctl/tensor/_elementwise_funcs.py +++ b/dpctl/tensor/_elementwise_funcs.py @@ -25,20 +25,22 @@ ) # U01: ==== ABS (x) -_abs_docstring_ = """ -abs(x, out=None, order='K') +_abs_docstring_ = r""" +abs(x, /, \*, out=None, order='K') Calculates the absolute value for each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. - Default: "K". + Memory layout of the new output array, + if parameter `out` is ``None``. + Default: `"K"`. + Returns: usm_ndarray: An array containing the element-wise absolute values. @@ -50,22 +52,25 @@ """ abs = UnaryElementwiseFunc("abs", ti._abs_result_type, ti._abs, _abs_docstring_) +del _abs_docstring_ # U02: ==== ACOS (x) -_acos_docstring = """ -acos(x, out=None, order='K') +_acos_docstring = r""" +acos(x, /, \*, out=None, order='K') Computes inverse cosine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise inverse cosine, in radians @@ -76,22 +81,25 @@ acos = UnaryElementwiseFunc( "acos", ti._acos_result_type, ti._acos, _acos_docstring ) +del _acos_docstring # U03: ===== ACOSH (x) -_acosh_docstring = """ -acosh(x, out=None, order='K') +_acosh_docstring = r""" +acosh(x, /, \*, out=None, order='K') Computes inverse hyperbolic cosine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise inverse hyperbolic cosine, in @@ -102,11 +110,12 @@ acosh = UnaryElementwiseFunc( "acosh", ti._acosh_result_type, ti._acosh, _acosh_docstring ) +del _acosh_docstring # B01: ===== ADD (x1, x2) -_add_docstring_ = """ -add(x1, x2, out=None, order='K') +_add_docstring_ = r""" +add(x1, x2, /, \*, out=None, order='K') Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -116,12 +125,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise sums. The data type of the @@ -134,22 +145,25 @@ _add_docstring_, binary_inplace_fn=ti._add_inplace, ) +del _add_docstring_ # U04: ===== ASIN (x) -_asin_docstring = """ -asin(x, out=None, order='K') +_asin_docstring = r""" +asin(x, /, \*, out=None, order='K') Computes inverse sine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise inverse sine, in radians @@ -160,22 +174,25 @@ asin = UnaryElementwiseFunc( "asin", ti._asin_result_type, ti._asin, _asin_docstring ) +del _asin_docstring # U05: ===== ASINH (x) -_asinh_docstring = """ -asinh(x, out=None, order='K') +_asinh_docstring = r""" +asinh(x, /, \*, out=None, order='K') Computes inverse hyperbolic sine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise inverse hyperbolic sine. @@ -186,22 +203,25 @@ asinh = UnaryElementwiseFunc( "asinh", ti._asinh_result_type, ti._asinh, _asinh_docstring ) +del _asinh_docstring # U06: ===== ATAN (x) -_atan_docstring = """ -atan(x, out=None, order='K') +_atan_docstring = r""" +atan(x, /, \*, out=None, order='K') Computes inverse tangent for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise inverse tangent, in radians @@ -212,10 +232,11 @@ atan = UnaryElementwiseFunc( "atan", ti._atan_result_type, ti._atan, _atan_docstring ) +del _atan_docstring # B02: ===== ATAN2 (x1, x2) -_atan2_docstring_ = """ -atan2(x1, x2, out=None, order='K') +_atan2_docstring_ = r""" +atan2(x1, x2, /, \*, out=None, order='K') Calculates the inverse tangent of the quotient `x1_i/x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the @@ -228,12 +249,14 @@ x2 (usm_ndarray): Second input array, also expected to have a real-valued floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the inverse tangent of the quotient `x1`/`x2`. @@ -244,22 +267,25 @@ atan2 = BinaryElementwiseFunc( "atan2", ti._atan2_result_type, ti._atan2, _atan2_docstring_ ) +del _atan2_docstring_ # U07: ===== ATANH (x) -_atanh_docstring = """ -atanh(x, out=None, order='K') +_atanh_docstring = r""" +atanh(x, /, \*, out=None, order='K') Computes hyperbolic inverse tangent for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise hyperbolic inverse tangent. @@ -270,10 +296,11 @@ atanh = UnaryElementwiseFunc( "atanh", ti._atanh_result_type, ti._atanh, _atanh_docstring ) +del _atanh_docstring # B03: ===== BITWISE_AND (x1, x2) -_bitwise_and_docstring_ = """ -bitwise_and(x1, x2, out=None, order='K') +_bitwise_and_docstring_ = r""" +bitwise_and(x1, x2, /, \*, out=None, order='K') Computes the bitwise AND of the underlying binary representation of each element `x1_i` of the input array `x1` with the respective element `x2_i` @@ -285,12 +312,14 @@ x2 (usm_ndarray): Second input array, also expected to have integer or boolean data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -304,10 +333,11 @@ _bitwise_and_docstring_, binary_inplace_fn=ti._bitwise_and_inplace, ) +del _bitwise_and_docstring_ # B04: ===== BITWISE_LEFT_SHIFT (x1, x2) -_bitwise_left_shift_docstring_ = """ -bitwise_left_shift(x1, x2, out=None, order='K') +_bitwise_left_shift_docstring_ = r""" +bitwise_left_shift(x1, x2, /, \*, out=None, order='K') Shifts the bits of each element `x1_i` of the input array x1 to the left by appending `x2_i` (i.e., the respective element in the input array `x2`) zeros to @@ -319,12 +349,14 @@ x2 (usm_ndarray): Second input array, also expected to have integer data type. Each element must be greater than or equal to 0. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -338,23 +370,26 @@ _bitwise_left_shift_docstring_, binary_inplace_fn=ti._bitwise_left_shift_inplace, ) +del _bitwise_left_shift_docstring_ # U08: ===== BITWISE_INVERT (x) -_bitwise_invert_docstring = """ -bitwise_invert(x, out=None, order='K') +_bitwise_invert_docstring = r""" +bitwise_invert(x, /, \*, out=None, order='K') Inverts (flips) each bit for each element `x_i` of the input array `x`. Args: x (usm_ndarray): Input array, expected to have integer or boolean data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. @@ -368,10 +403,11 @@ ti._bitwise_invert, _bitwise_invert_docstring, ) +del _bitwise_invert_docstring # B05: ===== BITWISE_OR (x1, x2) -_bitwise_or_docstring_ = """ -bitwise_or(x1, x2, out=None, order='K') +_bitwise_or_docstring_ = r""" +bitwise_or(x1, x2, /, \*, out=None, order='K') Computes the bitwise OR of the underlying binary representation of each element `x1_i` of the input array `x1` with the respective element `x2_i` @@ -383,12 +419,14 @@ x2 (usm_ndarray): Second input array, also expected to have integer or boolean data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -402,10 +440,11 @@ _bitwise_or_docstring_, binary_inplace_fn=ti._bitwise_or_inplace, ) +del _bitwise_or_docstring_ # B06: ===== BITWISE_RIGHT_SHIFT (x1, x2) -_bitwise_right_shift_docstring_ = """ -bitwise_right_shift(x1, x2, out=None, order='K') +_bitwise_right_shift_docstring_ = r""" +bitwise_right_shift(x1, x2, /, \*, out=None, order='K') Shifts the bits of each element `x1_i` of the input array `x1` to the right according to the respective element `x2_i` of the input array `x2`. @@ -416,12 +455,14 @@ x2 (usm_ndarray): Second input array, also expected to have integer data type. Each element must be greater than or equal to 0. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -435,11 +476,12 @@ _bitwise_right_shift_docstring_, binary_inplace_fn=ti._bitwise_right_shift_inplace, ) +del _bitwise_right_shift_docstring_ # B07: ===== BITWISE_XOR (x1, x2) -_bitwise_xor_docstring_ = """ -bitwise_xor(x1, x2, out=None, order='K') +_bitwise_xor_docstring_ = r""" +bitwise_xor(x1, x2, /, \*, out=None, order='K') Computes the bitwise XOR of the underlying binary representation of each element `x1_i` of the input array `x1` with the respective element `x2_i` @@ -451,12 +493,14 @@ x2 (usm_ndarray): Second input array, also expected to have integer or boolean data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -470,11 +514,12 @@ _bitwise_xor_docstring_, binary_inplace_fn=ti._bitwise_xor_inplace, ) +del _bitwise_xor_docstring_ # U09: ==== CEIL (x) -_ceil_docstring = """ -ceil(x, out=None, order='K') +_ceil_docstring = r""" +ceil(x, /, \*, out=None, order='K') Returns the ceiling for each element `x_i` for input array `x`. @@ -483,12 +528,14 @@ Args: x (usm_ndarray): Input array, expected to have a real-valued data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise ceiling. @@ -497,22 +544,25 @@ ceil = UnaryElementwiseFunc( "ceil", ti._ceil_result_type, ti._ceil, _ceil_docstring ) +del _ceil_docstring # U10: ==== CONJ (x) -_conj_docstring = """ -conj(x, out=None, order='K') +_conj_docstring = r""" +conj(x, /, \*, out=None, order='K') Computes conjugate of each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a numeric data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise conjugate values. @@ -521,22 +571,25 @@ conj = UnaryElementwiseFunc( "conj", ti._conj_result_type, ti._conj, _conj_docstring ) +del _conj_docstring # U11: ==== COS (x) -_cos_docstring = """ -cos(x, out=None, order='K') +_cos_docstring = r""" +cos(x, /, \*, out=None, order='K') Computes cosine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise cosine. The data type @@ -544,22 +597,25 @@ """ cos = UnaryElementwiseFunc("cos", ti._cos_result_type, ti._cos, _cos_docstring) +del _cos_docstring # U12: ==== COSH (x) -_cosh_docstring = """ -cosh(x, out=None, order='K') +_cosh_docstring = r""" +cosh(x, /, \*, out=None, order='K') Computes hyperbolic cosine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise hyperbolic cosine. The data type @@ -569,10 +625,11 @@ cosh = UnaryElementwiseFunc( "cosh", ti._cosh_result_type, ti._cosh, _cosh_docstring ) +del _cosh_docstring # B08: ==== DIVIDE (x1, x2) -_divide_docstring_ = """ -divide(x1, x2, out=None, order='K') +_divide_docstring_ = r""" +divide(x1, x2, /, \*, out=None, order='K') Calculates the ratio for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -582,12 +639,14 @@ First input array, expected to have a floating-point data type. x2 (usm_ndarray): Second input array, also expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise division. The data type @@ -602,10 +661,11 @@ binary_inplace_fn=ti._divide_inplace, acceptance_fn=_acceptance_fn_divide, ) +del _divide_docstring_ # B09: ==== EQUAL (x1, x2) -_equal_docstring_ = """ -equal(x1, x2, out=None, order='K') +_equal_docstring_ = r""" +equal(x1, x2, /, \*, out=None, order='K') Calculates equality test results for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -615,12 +675,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise equality comparison. @@ -630,22 +692,25 @@ equal = BinaryElementwiseFunc( "equal", ti._equal_result_type, ti._equal, _equal_docstring_ ) +del _equal_docstring_ # U13: ==== EXP (x) -_exp_docstring = """ -exp(x, out=None, order='K') +_exp_docstring = r""" +exp(x, /, \*, out=None, order='K') Computes the exponential for each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise exponential of x. @@ -654,10 +719,11 @@ """ exp = UnaryElementwiseFunc("exp", ti._exp_result_type, ti._exp, _exp_docstring) +del _exp_docstring # U14: ==== EXPM1 (x) -_expm1_docstring = """ -expm1(x, out=None, order='K') +_expm1_docstring = r""" +expm1(x, /, \*, out=None, order='K') Computes the exponential minus 1 for each element `x_i` of input array `x`. @@ -670,9 +736,10 @@ Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): memory layout of the new - output array, if parameter `out` is `None`. + output array, if parameter `out` is ``None``. Default: "K". -Return: + +Returns: usm_ndarray: An array containing the element-wise `exp(x) - 1` results. The data type of the returned array is determined by the Type @@ -682,10 +749,11 @@ expm1 = UnaryElementwiseFunc( "expm1", ti._expm1_result_type, ti._expm1, _expm1_docstring ) +del _expm1_docstring # U15: ==== FLOOR (x) -_floor_docstring = """ -floor(x, out=None, order='K') +_floor_docstring = r""" +floor(x, /, \*, out=None, order='K') Returns the floor for each element `x_i` for input array `x`. @@ -694,12 +762,14 @@ Args: x (usm_ndarray): Input array, expected to have a real-valued data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise floor. @@ -708,10 +778,11 @@ floor = UnaryElementwiseFunc( "floor", ti._floor_result_type, ti._floor, _floor_docstring ) +del _floor_docstring # B10: ==== FLOOR_DIVIDE (x1, x2) -_floor_divide_docstring_ = """ -floor_divide(x1, x2, out=None, order='K') +_floor_divide_docstring_ = r""" +floor_divide(x1, x2, /, \*, out=None, order='K') Calculates the ratio for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2` to the greatest @@ -723,6 +794,14 @@ x2 (usm_ndarray): Second input array, also expected to have a real-valued or boolean data type. + out (Union[usm_ndarray, None], optional): + Output array to populate. + Array must have the correct shape and the expected data type. + order ("C","F","A","K", optional): + Memory layout of the new output array, if parameter + `out` is ``None``. + Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise floor of division. @@ -737,10 +816,11 @@ _floor_divide_docstring_, binary_inplace_fn=ti._floor_divide_inplace, ) +del _floor_divide_docstring_ # B11: ==== GREATER (x1, x2) -_greater_docstring_ = """ -greater(x1, x2, out=None, order='K') +_greater_docstring_ = r""" +greater(x1, x2, /, \*, out=None, order='K') Computes the greater-than test results for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -750,12 +830,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise greater-than comparison. @@ -765,10 +847,11 @@ greater = BinaryElementwiseFunc( "greater", ti._greater_result_type, ti._greater, _greater_docstring_ ) +del _greater_docstring_ # B12: ==== GREATER_EQUAL (x1, x2) -_greater_equal_docstring_ = """ -greater_equal(x1, x2, out=None, order='K') +_greater_equal_docstring_ = r""" +greater_equal(x1, x2, /, \*, out=None, order='K') Computes the greater-than or equal-to test results for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -778,12 +861,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise greater-than or equal-to @@ -797,22 +882,25 @@ ti._greater_equal, _greater_equal_docstring_, ) +del _greater_equal_docstring_ # U16: ==== IMAG (x) -_imag_docstring = """ -imag(x, out=None, order='K') +_imag_docstring = r""" +imag(x, /, \*, out=None, order='K') Computes imaginary part of each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise imaginary component of input. @@ -825,22 +913,25 @@ imag = UnaryElementwiseFunc( "imag", ti._imag_result_type, ti._imag, _imag_docstring ) +del _imag_docstring # U17: ==== ISFINITE (x) -_isfinite_docstring_ = """ -isfinite(x, out=None, order='K') +_isfinite_docstring_ = r""" +isfinite(x, /, \*, out=None, order='K') Test if each element of input array is a finite number. Args: x (usm_ndarray): Input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array which is True where `x` is not positive infinity, @@ -851,22 +942,25 @@ isfinite = UnaryElementwiseFunc( "isfinite", ti._isfinite_result_type, ti._isfinite, _isfinite_docstring_ ) +del _isfinite_docstring_ # U18: ==== ISINF (x) -_isinf_docstring_ = """ -isinf(x, out=None, order='K') +_isinf_docstring_ = r""" +isinf(x, /, \*, out=None, order='K') Test if each element of input array is an infinity. Args: x (usm_ndarray): Input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array which is True where `x` is positive or negative infinity, @@ -876,22 +970,25 @@ isinf = UnaryElementwiseFunc( "isinf", ti._isinf_result_type, ti._isinf, _isinf_docstring_ ) +del _isinf_docstring_ # U19: ==== ISNAN (x) -_isnan_docstring_ = """ -isnan(x, out=None, order='K') +_isnan_docstring_ = r""" +isnan(x, /, \*, out=None, order='K') Test if each element of an input array is a NaN. Args: x (usm_ndarray): Input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array which is True where x is NaN, False otherwise. @@ -901,10 +998,11 @@ isnan = UnaryElementwiseFunc( "isnan", ti._isnan_result_type, ti._isnan, _isnan_docstring_ ) +del _isnan_docstring_ # B13: ==== LESS (x1, x2) -_less_docstring_ = """ -less(x1, x2, out=None, order='K') +_less_docstring_ = r""" +less(x1, x2, /, \*, out=None, order='K') Computes the less-than test results for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -914,12 +1012,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise less-than comparison. @@ -929,10 +1029,12 @@ less = BinaryElementwiseFunc( "less", ti._less_result_type, ti._less, _less_docstring_ ) +del _less_docstring_ + # B14: ==== LESS_EQUAL (x1, x2) -_less_equal_docstring_ = """ -less_equal(x1, x2, out=None, order='K') +_less_equal_docstring_ = r""" +less_equal(x1, x2, /, \*, out=None, order='K') Computes the less-than or equal-to test results for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -942,12 +1044,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise less-than or equal-to @@ -960,10 +1064,11 @@ ti._less_equal, _less_equal_docstring_, ) +del _less_equal_docstring_ # U20: ==== LOG (x) -_log_docstring = """ -log(x, out=None, order='K') +_log_docstring = r""" +log(x, /, \*, out=None, order='K') Computes the natural logarithm for each element `x_i` of input array `x`. @@ -974,9 +1079,10 @@ Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): memory layout of the new - output array, if parameter `out` is `None`. + output array, if parameter `out` is ``None``. Default: "K". -Return: + +Returns: usm_ndarray: An array containing the element-wise natural logarithm values. The data type of the returned array is determined by the Type @@ -984,10 +1090,11 @@ """ log = UnaryElementwiseFunc("log", ti._log_result_type, ti._log, _log_docstring) +del _log_docstring # U21: ==== LOG1P (x) -_log1p_docstring = """ -log1p(x, out=None, order='K') +_log1p_docstring = r""" +log1p(x, /, \*, out=None, order='K') Computes the natural logarithm of (1 + `x`) for each element `x_i` of input array `x`. @@ -1001,9 +1108,10 @@ Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): memory layout of the new - output array, if parameter `out` is `None`. + output array, if parameter `out` is ``None``. Default: "K". -Return: + +Returns: usm_ndarray: An array containing the element-wise `log(1 + x)` results. The data type of the returned array is determined by the Type Promotion Rules. @@ -1012,22 +1120,25 @@ log1p = UnaryElementwiseFunc( "log1p", ti._log1p_result_type, ti._log1p, _log1p_docstring ) +del _log1p_docstring # U22: ==== LOG2 (x) -_log2_docstring_ = """ -log2(x, out=None, order='K') +_log2_docstring_ = r""" +log2(x, /, \*, out=None, order='K') Computes the base-2 logarithm for each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise base-2 logarithm of `x`. @@ -1038,22 +1149,25 @@ log2 = UnaryElementwiseFunc( "log2", ti._log2_result_type, ti._log2, _log2_docstring_ ) +del _log2_docstring_ # U23: ==== LOG10 (x) -_log10_docstring_ = """ -log10(x, out=None, order='K') +_log10_docstring_ = r""" +log10(x, /, \*, out=None, order='K') Computes the base-10 logarithm for each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. - Default: "K". + Memory layout of the new output array, if parameter + `out` is ``None``. + Default: `"K"`. + Returns: usm_ndarray: An array containing the element-wise base-10 logarithm of `x`. @@ -1064,10 +1178,11 @@ log10 = UnaryElementwiseFunc( "log10", ti._log10_result_type, ti._log10, _log10_docstring_ ) +del _log10_docstring_ # B15: ==== LOGADDEXP (x1, x2) -_logaddexp_docstring_ = """ -logaddexp(x1, x2, out=None, order='K') +_logaddexp_docstring_ = r""" +logaddexp(x1, x2, /, \*, out=None, order='K') Calculates the natural logarithm of the sum of exponentials for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input @@ -1083,12 +1198,14 @@ x2 (usm_ndarray): Second input array, also expected to have a real-valued floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -1098,10 +1215,11 @@ logaddexp = BinaryElementwiseFunc( "logaddexp", ti._logaddexp_result_type, ti._logaddexp, _logaddexp_docstring_ ) +del _logaddexp_docstring_ # B16: ==== LOGICAL_AND (x1, x2) -_logical_and_docstring_ = """ -logical_and(x1, x2, out=None, order='K') +_logical_and_docstring_ = r""" +logical_and(x1, x2, /, \*, out=None, order='K') Computes the logical AND for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1111,12 +1229,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise logical AND results. @@ -1127,10 +1247,11 @@ ti._logical_and, _logical_and_docstring_, ) +del _logical_and_docstring_ # U24: ==== LOGICAL_NOT (x) -_logical_not_docstring = """ -logical_not(x, out=None, order='K') +_logical_not_docstring = r""" +logical_not(x, /, \*, out=None, order='K') Computes the logical NOT for each element `x_i` of input array `x`. @@ -1141,9 +1262,10 @@ Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): memory layout of the new - output array, if parameter `out` is `None`. + output array, if parameter `out` is ``None``. Default: "K". -Return: + +Returns: usm_ndarray: An array containing the element-wise logical NOT results. """ @@ -1154,10 +1276,11 @@ ti._logical_not, _logical_not_docstring, ) +del _logical_not_docstring # B17: ==== LOGICAL_OR (x1, x2) -_logical_or_docstring_ = """ -logical_or(x1, x2, out=None, order='K') +_logical_or_docstring_ = r""" +logical_or(x1, x2, /, \*, out=None, order='K') Computes the logical OR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1167,12 +1290,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise logical OR results. @@ -1183,10 +1308,11 @@ ti._logical_or, _logical_or_docstring_, ) +del _logical_or_docstring_ # B18: ==== LOGICAL_XOR (x1, x2) -_logical_xor_docstring_ = """ -logical_xor(x1, x2, out=None, order='K') +_logical_xor_docstring_ = r""" +logical_xor(x1, x2, /, \*, out=None, order='K') Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1196,12 +1322,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise logical XOR results. @@ -1212,10 +1340,11 @@ ti._logical_xor, _logical_xor_docstring_, ) +del _logical_xor_docstring_ # B26: ==== MAXIMUM (x1, x2) -_maximum_docstring_ = """ -maximum(x1, x2, out=None, order='K') +_maximum_docstring_ = r""" +maximum(x1, x2, /, \*, out=None, order='K') Compares two input arrays `x1` and `x2` and returns a new array containing the element-wise maxima. @@ -1225,12 +1354,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise maxima. The data type of @@ -1242,10 +1373,11 @@ ti._maximum, _maximum_docstring_, ) +del _maximum_docstring_ # B27: ==== MINIMUM (x1, x2) -_minimum_docstring_ = """ -minimum(x1, x2, out=None, order='K') +_minimum_docstring_ = r""" +minimum(x1, x2, /, \*, out=None, order='K') Compares two input arrays `x1` and `x2` and returns a new array containing the element-wise minima. @@ -1255,12 +1387,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise minima. The data type of @@ -1272,10 +1406,11 @@ ti._minimum, _minimum_docstring_, ) +del _minimum_docstring_ # B19: ==== MULTIPLY (x1, x2) -_multiply_docstring_ = """ -multiply(x1, x2, out=None, order='K') +_multiply_docstring_ = r""" +multiply(x1, x2, /, \*, out=None, order='K') Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1285,12 +1420,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise products. The data type of @@ -1303,10 +1440,11 @@ _multiply_docstring_, binary_inplace_fn=ti._multiply_inplace, ) +del _multiply_docstring_ # U25: ==== NEGATIVE (x) -_negative_docstring_ = """ -negative(x, out=None, order='K') +_negative_docstring_ = r""" +negative(x, /, \*, out=None, order='K') Computes the numerical negative for each element `x_i` of input array `x`. @@ -1317,9 +1455,10 @@ Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): memory layout of the new - output array, if parameter `out` is `None`. + output array, if parameter `out` is ``None``. Default: "K". -Return: + +Returns: usm_ndarray: An array containing the negative of `x`. """ @@ -1331,10 +1470,11 @@ _negative_docstring_, acceptance_fn=_acceptance_fn_negative, ) +del _negative_docstring_ # B20: ==== NOT_EQUAL (x1, x2) -_not_equal_docstring_ = """ -not_equal(x1, x2, out=None, order='K') +_not_equal_docstring_ = r""" +not_equal(x1, x2, /, \*, out=None, order='K') Calculates inequality test results for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1344,12 +1484,14 @@ First input array. x2 (usm_ndarray): Second input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise inequality comparison. @@ -1359,12 +1501,14 @@ not_equal = BinaryElementwiseFunc( "not_equal", ti._not_equal_result_type, ti._not_equal, _not_equal_docstring_ ) +del _not_equal_docstring_ # U26: ==== POSITIVE (x) -_positive_docstring_ = """ -positive(x, out=None, order='K') +_positive_docstring_ = r""" +positive(x, /, \*, out=None, order='K') Computes the numerical positive for each element `x_i` of input array `x`. + Args: x (usm_ndarray): Input array, expected to have a numeric data type. @@ -1372,9 +1516,10 @@ Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): memory layout of the new - output array, if parameter `out` is `None`. + output array, if parameter `out` is ``None``. Default: "K". -Return: + +Returns: usm_ndarray: An array containing the positive of `x`. """ @@ -1382,10 +1527,11 @@ positive = UnaryElementwiseFunc( "positive", ti._positive_result_type, ti._positive, _positive_docstring_ ) +del _positive_docstring_ # B21: ==== POW (x1, x2) -_pow_docstring_ = """ -pow(x1, x2, out=None, order='K') +_pow_docstring_ = r""" +pow(x1, x2, /, \*, out=None, order='K') Calculates `x1_i` raised to `x2_i` for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1395,6 +1541,13 @@ First input array, expected to have a numeric data type. x2 (usm_ndarray): Second input array, also expected to have a numeric data type. + out (usm_ndarray): + Output array to populate. Array must have the correct + shape and the expected data type. + order ("C","F","A","K", optional): memory layout of the new + output array, if parameter `out` is ``None``. + Default: "K". + Returns: usm_ndarray: An array containing the bases in `x1` raised to the exponents in `x2` @@ -1408,22 +1561,25 @@ _pow_docstring_, binary_inplace_fn=ti._pow_inplace, ) +del _pow_docstring_ # U40: ==== PROJ (x) -_proj_docstring = """ -proj(x, out=None, order='K') +_proj_docstring = r""" +proj(x, /, \*, out=None, order='K') Computes projection of each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a complex data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise projection. @@ -1432,22 +1588,25 @@ proj = UnaryElementwiseFunc( "proj", ti._proj_result_type, ti._proj, _proj_docstring ) +del _proj_docstring # U27: ==== REAL (x) -_real_docstring = """ -real(x, out=None, order='K') +_real_docstring = r""" +real(x, /, \*, out=None, order='K') Computes real part of each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise real component of input. @@ -1460,10 +1619,11 @@ real = UnaryElementwiseFunc( "real", ti._real_result_type, ti._real, _real_docstring ) +del _real_docstring # B22: ==== REMAINDER (x1, x2) -_remainder_docstring_ = """ -remainder(x1, x2, out=None, order='K') +_remainder_docstring_ = r""" +remainder(x1, x2, /, \*, out=None, order='K') Calculates the remainder of division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. @@ -1475,12 +1635,14 @@ First input array, expected to have a real-valued data type. x2 (usm_ndarray): Second input array, also expected to have a real-valued data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise remainders. Each remainder has the @@ -1494,10 +1656,11 @@ _remainder_docstring_, binary_inplace_fn=ti._remainder_inplace, ) +del _remainder_docstring_ # U28: ==== ROUND (x) -_round_docstring = """ -round(x, out=None, order='K') +_round_docstring = r""" +round(x, /, \*, out=None, order='K') Rounds each element `x_i` of the input array `x` to the nearest integer-valued number. @@ -1508,12 +1671,14 @@ Args: x (usm_ndarray): Input array, expected to have a real-valued data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise rounded values. @@ -1522,10 +1687,11 @@ round = UnaryElementwiseFunc( "round", ti._round_result_type, ti._round, _round_docstring ) +del _round_docstring # U29: ==== SIGN (x) -_sign_docstring = """ -sign(x, out=None, order='K') +_sign_docstring = r""" +sign(x, /, \*, out=None, order='K') Computes an indication of the sign of each element `x_i` of input array `x` using the signum function. @@ -1536,12 +1702,14 @@ Args: x (usm_ndarray): Input array, expected to have a numeric data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise result of the signum function. The @@ -1552,10 +1720,11 @@ sign = UnaryElementwiseFunc( "sign", ti._sign_result_type, ti._sign, _sign_docstring ) +del _sign_docstring # U41: ==== SIGNBIT (x) -_signbit_docstring = """ -signbit(x, out=None, order='K') +_signbit_docstring = r""" +signbit(x, /, \*, out=None, order='K') Computes an indication of whether the sign bit of each element `x_i` of input array `x` is set. @@ -1563,12 +1732,14 @@ Args: x (usm_ndarray): Input array, expected to have a real-valued floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise signbit results. The returned array @@ -1578,22 +1749,25 @@ signbit = UnaryElementwiseFunc( "signbit", ti._signbit_result_type, ti._signbit, _signbit_docstring ) +del _signbit_docstring # U30: ==== SIN (x) -_sin_docstring = """ -sin(x, out=None, order='K') +_sin_docstring = r""" +sin(x, /, \*, out=None, order='K') Computes sine for each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise sine. The data type of the @@ -1601,22 +1775,25 @@ """ sin = UnaryElementwiseFunc("sin", ti._sin_result_type, ti._sin, _sin_docstring) +del _sin_docstring # U31: ==== SINH (x) -_sinh_docstring = """ -sinh(x, out=None, order='K') +_sinh_docstring = r""" +sinh(x, /, \*, out=None, order='K') Computes hyperbolic sine for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise hyperbolic sine. The data type @@ -1626,22 +1803,25 @@ sinh = UnaryElementwiseFunc( "sinh", ti._sinh_result_type, ti._sinh, _sinh_docstring ) +del _sinh_docstring # U32: ==== SQUARE (x) -_square_docstring_ = """ -square(x, out=None, order='K') +_square_docstring_ = r""" +square(x, /, \*, out=None, order='K') Squares each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array, expected to have numeric data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise squares of `x`. The data type of @@ -1651,22 +1831,25 @@ square = UnaryElementwiseFunc( "square", ti._square_result_type, ti._square, _square_docstring_ ) +del _square_docstring_ # U33: ==== SQRT (x) -_sqrt_docstring_ = """ -sqrt(x, out=None, order='K') +_sqrt_docstring_ = r""" +sqrt(x, /, \*, out=None, order='K') Computes the positive square-root for each element `x_i` of input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise positive square-roots of `x`. The @@ -1677,10 +1860,11 @@ sqrt = UnaryElementwiseFunc( "sqrt", ti._sqrt_result_type, ti._sqrt, _sqrt_docstring_ ) +del _sqrt_docstring_ # B23: ==== SUBTRACT (x1, x2) -_subtract_docstring_ = """ -subtract(x1, x2, out=None, order='K') +_subtract_docstring_ = r""" +subtract(x1, x2, /, \*, out=None, order='K') Calculates the difference between each element `x1_i` of the input array `x1` and the respective element `x2_i` of the input array `x2`. @@ -1690,12 +1874,14 @@ First input array, expected to have a numeric data type. x2 (usm_ndarray): Second input array, also expected to have a numeric data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise differences. The data type @@ -1709,22 +1895,25 @@ binary_inplace_fn=ti._subtract_inplace, acceptance_fn=_acceptance_fn_subtract, ) +del _subtract_docstring_ # U34: ==== TAN (x) -_tan_docstring = """ -tan(x, out=None, order='K') +_tan_docstring = r""" +tan(x, /, \*, out=None, order='K') Computes tangent for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise tangent. The data type @@ -1732,22 +1921,25 @@ """ tan = UnaryElementwiseFunc("tan", ti._tan_result_type, ti._tan, _tan_docstring) +del _tan_docstring # U35: ==== TANH (x) -_tanh_docstring = """ -tanh(x, out=None, order='K') +_tanh_docstring = r""" +tanh(x, /, \*, out=None, order='K') Computes hyperbolic tangent for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise hyperbolic tangent. The data type @@ -1757,10 +1949,11 @@ tanh = UnaryElementwiseFunc( "tanh", ti._tanh_result_type, ti._tanh, _tanh_docstring ) +del _tanh_docstring # U36: ==== TRUNC (x) -_trunc_docstring = """ -trunc(x, out=None, order='K') +_trunc_docstring = r""" +trunc(x, /, \*, out=None, order='K') Returns the truncated value for each element `x_i` for input array `x`. @@ -1771,12 +1964,14 @@ Args: x (usm_ndarray): Input array, expected to have a real-valued data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the result of element-wise division. The data type @@ -1785,11 +1980,12 @@ trunc = UnaryElementwiseFunc( "trunc", ti._trunc_result_type, ti._trunc, _trunc_docstring ) +del _trunc_docstring # B24: ==== HYPOT (x1, x2) -_hypot_docstring_ = """ -hypot(x1, x2, out=None, order='K') +_hypot_docstring_ = r""" +hypot(x1, x2, /, \*, out=None, order='K') Calculates the hypotenuse for a right triangle with "legs" `x1_i` and `x2_i` of input arrays `x1` and `x2`. @@ -1801,12 +1997,14 @@ x2 (usm_ndarray): Second input array, also expected to have a real-valued floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array must have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise hypotenuse. The data type @@ -1816,23 +2014,26 @@ hypot = BinaryElementwiseFunc( "hypot", ti._hypot_result_type, ti._hypot, _hypot_docstring_ ) +del _hypot_docstring_ # U37: ==== CBRT (x) -_cbrt_docstring_ = """ -cbrt(x, out=None, order='K') +_cbrt_docstring_ = r""" +cbrt(x, /, \*, out=None, order='K') Computes positive cube-root for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a real floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise positive cube-root. @@ -1843,23 +2044,26 @@ cbrt = UnaryElementwiseFunc( "cbrt", ti._cbrt_result_type, ti._cbrt, _cbrt_docstring_ ) +del _cbrt_docstring_ # U38: ==== EXP2 (x) -_exp2_docstring_ = """ -exp2(x, out=None, order='K') +_exp2_docstring_ = r""" +exp2(x, /, \*, out=None, order='K') Computes the base-2 exponential for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise base-2 exponentials. @@ -1870,11 +2074,12 @@ exp2 = UnaryElementwiseFunc( "exp2", ti._exp2_result_type, ti._exp2, _exp2_docstring_ ) +del _exp2_docstring_ # B25: ==== COPYSIGN (x1, x2) -_copysign_docstring_ = """ -copysign(x1, x2, out=None, order='K') +_copysign_docstring_ = r""" +copysign(x1, x2, /, \*, out=None, order='K') Composes a floating-point value with the magnitude of `x1_i` and the sign of `x2_i` for each element of input arrays `x1` and `x2`. @@ -1885,12 +2090,14 @@ x2 (usm_ndarray): Second input array, also expected to have a real floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise results. The data type @@ -1902,23 +2109,26 @@ ti._copysign, _copysign_docstring_, ) +del _copysign_docstring_ # U39: ==== RSQRT (x) -_rsqrt_docstring_ = """ -rsqrt(x, out=None, order='K') +_rsqrt_docstring_ = r""" +rsqrt(x, /, \*, out=None, order='K') Computes the reciprocal square-root for each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a real floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_ndarray: An array containing the element-wise reciprocal square-root. @@ -1929,23 +2139,26 @@ rsqrt = UnaryElementwiseFunc( "rsqrt", ti._rsqrt_result_type, ti._rsqrt, _rsqrt_docstring_ ) +del _rsqrt_docstring_ # U42: ==== RECIPROCAL (x) -_reciprocal_docstring = """ -reciprocal(x, out=None, order='K') +_reciprocal_docstring = r""" +reciprocal(x, /, \*, out=None, order='K') Computes the reciprocal of each element `x_i` for input array `x`. Args: x (usm_ndarray): Input array, expected to have a real-valued floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_narray: An array containing the element-wise reciprocals. @@ -1960,11 +2173,12 @@ _reciprocal_docstring, acceptance_fn=_acceptance_fn_reciprocal, ) +del _reciprocal_docstring # U43: ==== ANGLE (x) -_angle_docstring = """ -angle(x, out=None, order='K') +_angle_docstring = r""" +angle(x, /, \*, out=None, order='K') Computes the phase angle (also called the argument) of each element `x_i` for input array `x`. @@ -1972,12 +2186,14 @@ Args: x (usm_ndarray): Input array, expected to have a complex-valued floating-point data type. - out ({None, usm_ndarray}, optional): + out (Union[usm_ndarray, None], optional): Output array to populate. Array have the correct shape and the expected data type. order ("C","F","A","K", optional): - Memory layout of the newly output array, if parameter `out` is `None`. + Memory layout of the new output array, if parameter + `out` is ``None``. Default: "K". + Returns: usm_narray: An array containing the element-wise phase angles. @@ -1991,3 +2207,6 @@ ti._angle, _angle_docstring, ) +del _angle_docstring + +del ti diff --git a/dpctl/tensor/_manipulation_functions.py b/dpctl/tensor/_manipulation_functions.py index 3480b3a0d5..274ae75148 100644 --- a/dpctl/tensor/_manipulation_functions.py +++ b/dpctl/tensor/_manipulation_functions.py @@ -974,7 +974,10 @@ def tile(x, repetitions): # case of empty input if x.size == 0: return dpt.empty( - res_shape, x.dtype, usm_type=x.usm_type, sycl_queue=x.sycl_queue + res_shape, + dtype=x.dtype, + usm_type=x.usm_type, + sycl_queue=x.sycl_queue, ) in_sh = x.shape if res_shape == in_sh: @@ -997,7 +1000,9 @@ def tile(x, repetitions): broadcast_sh.extend([reps, sh]) expanded_sh.extend([1, sh]) exec_q = x.sycl_queue - res = dpt.empty((out_sz,), x.dtype, usm_type=x.usm_type, sycl_queue=exec_q) + xdt = x.dtype + xut = x.usm_type + res = dpt.empty((out_sz,), dtype=xdt, usm_type=xut, sycl_queue=exec_q) # no need to copy data for empty output if out_sz > 0: x = dpt.broadcast_to( diff --git a/dpctl/tensor/_statistical_functions.py b/dpctl/tensor/_statistical_functions.py index b238aab2f4..2b8e65d304 100644 --- a/dpctl/tensor/_statistical_functions.py +++ b/dpctl/tensor/_statistical_functions.py @@ -148,7 +148,9 @@ def _var_impl(x, axis, correction, keepdims): div = max(nelems - correction, 0) if not div: div = dpt.nan - div_ary = dpt.asarray(div, res_dt, usm_type=res_usm_type, sycl_queue=q) + div_ary = dpt.asarray( + div, dtype=res_dt, usm_type=res_usm_type, sycl_queue=q + ) # divide in-place again if div_ary.shape != res_shape: div_ary = dpt.broadcast_to(div_ary, res.shape) diff --git a/dpctl/tests/elementwise/test_add.py b/dpctl/tests/elementwise/test_add.py index 78cbebbe5b..9edc8399e8 100644 --- a/dpctl/tests/elementwise/test_add.py +++ b/dpctl/tests/elementwise/test_add.py @@ -15,10 +15,10 @@ # limitations under the License. import ctypes +import re import numpy as np import pytest -from numpy.testing import assert_raises_regex import dpctl import dpctl.tensor as dpt @@ -280,48 +280,36 @@ def test_add_errors(): ar1 = dpt.ones(2, dtype="float32", sycl_queue=gpu_queue) ar2 = dpt.ones_like(ar1, sycl_queue=gpu_queue) y = dpt.empty_like(ar1, sycl_queue=cpu_queue) - assert_raises_regex( - ExecutionPlacementError, - "Input and output allocation queues are not compatible", - dpt.add, - ar1, - ar2, - y, + with pytest.raises(ExecutionPlacementError) as excinfo: + dpt.add(ar1, ar2, out=y) + assert "Input and output allocation queues are not compatible" in str( + excinfo.value ) ar1 = dpt.ones(2, dtype="float32") ar2 = dpt.ones_like(ar1, dtype="int32") y = dpt.empty(3) - assert_raises_regex( - ValueError, - "The shape of input and output arrays are inconsistent", - dpt.add, - ar1, - ar2, - y, + with pytest.raises(ValueError) as excinfo: + dpt.add(ar1, ar2, out=y) + assert "The shape of input and output arrays are inconsistent" in str( + excinfo.value ) ar1 = np.ones(2, dtype="float32") ar2 = np.ones_like(ar1, dtype="int32") - assert_raises_regex( - ExecutionPlacementError, + with pytest.raises(ExecutionPlacementError) as excinfo: + dpt.add(ar1, ar2) + assert re.match( "Execution placement can not be unambiguously inferred.*", - dpt.add, - ar1, - ar2, + str(excinfo.value), ) ar1 = dpt.ones(2, dtype="float32") ar2 = dpt.ones_like(ar1, dtype="int32") y = np.empty_like(ar1) - assert_raises_regex( - TypeError, - "output array must be of usm_ndarray type", - dpt.add, - ar1, - ar2, - y, - ) + with pytest.raises(TypeError) as excinfo: + dpt.add(ar1, ar2, out=y) + assert "output array must be of usm_ndarray type" in str(excinfo.value) @pytest.mark.parametrize("dtype", _all_dtypes) @@ -335,9 +323,9 @@ def test_add_dtype_error( ar2 = dpt.ones_like(ar1, dtype="f4") y = dpt.zeros_like(ar1, dtype="int8") - assert_raises_regex( - ValueError, "Output array of type.*is needed", dpt.add, ar1, ar2, y - ) + with pytest.raises(ValueError) as excinfo: + dpt.add(ar1, ar2, out=y) + assert re.match("Output array of type.*is needed", str(excinfo.value)) @pytest.mark.parametrize("dtype", _all_dtypes) diff --git a/dpctl/tests/elementwise/test_equal.py b/dpctl/tests/elementwise/test_equal.py index c31f9bede3..b467d0ba30 100644 --- a/dpctl/tests/elementwise/test_equal.py +++ b/dpctl/tests/elementwise/test_equal.py @@ -128,7 +128,7 @@ def test_equal_broadcasting(): assert (dpt.asnumpy(r2) == expected).all() r3 = dpt.empty_like(m, dtype="?") - dpt.equal(m, v, r3) + dpt.equal(m, v, out=r3) assert (dpt.asnumpy(r3) == expected).all() diff --git a/dpctl/tests/elementwise/test_floor_ceil_trunc.py b/dpctl/tests/elementwise/test_floor_ceil_trunc.py index 2c9c36fdbb..b5ec1b6c4e 100644 --- a/dpctl/tests/elementwise/test_floor_ceil_trunc.py +++ b/dpctl/tests/elementwise/test_floor_ceil_trunc.py @@ -15,14 +15,11 @@ # limitations under the License. import itertools +import re import numpy as np import pytest -from numpy.testing import ( - assert_allclose, - assert_array_equal, - assert_raises_regex, -) +from numpy.testing import assert_allclose, assert_array_equal import dpctl.tensor as dpt from dpctl.tests.helper import get_queue_or_skip, skip_if_dtype_not_supported @@ -99,9 +96,9 @@ def test_floor_ceil_trunc_error_dtype(dpt_call, dtype): x = dpt.zeros(5, dtype=dtype) y = dpt.empty_like(x, dtype="b1") - assert_raises_regex( - ValueError, "Output array of type.*is needed", dpt_call, x, y - ) + with pytest.raises(ValueError) as excinfo: + dpt_call(x, out=y) + assert re.match("Output array of type.*is needed", str(excinfo.value)) @pytest.mark.parametrize("np_call, dpt_call", _all_funcs) diff --git a/dpctl/tests/elementwise/test_hyperbolic.py b/dpctl/tests/elementwise/test_hyperbolic.py index f570722cb8..b6bb4fabe7 100644 --- a/dpctl/tests/elementwise/test_hyperbolic.py +++ b/dpctl/tests/elementwise/test_hyperbolic.py @@ -16,10 +16,11 @@ import itertools import os +import re import numpy as np import pytest -from numpy.testing import assert_allclose, assert_raises_regex +from numpy.testing import assert_allclose import dpctl.tensor as dpt from dpctl.tests.helper import get_queue_or_skip, skip_if_dtype_not_supported @@ -186,9 +187,9 @@ def test_hyper_error_dtype(callable, dtype): x = dpt.ones(5, dtype=dtype) y = dpt.empty_like(x, dtype="int16") - assert_raises_regex( - ValueError, "Output array of type.*is needed", callable, x, y - ) + with pytest.raises(ValueError) as excinfo: + callable(x, out=y) + assert re.match("Output array of type.*is needed", str(excinfo.value)) @pytest.mark.parametrize("np_call, dpt_call", _all_funcs) diff --git a/dpctl/tests/elementwise/test_logaddexp.py b/dpctl/tests/elementwise/test_logaddexp.py index 1a8eb9df42..3f01ca1d86 100644 --- a/dpctl/tests/elementwise/test_logaddexp.py +++ b/dpctl/tests/elementwise/test_logaddexp.py @@ -15,10 +15,11 @@ # limitations under the License. import ctypes +import re import numpy as np import pytest -from numpy.testing import assert_allclose, assert_raises_regex +from numpy.testing import assert_allclose import dpctl import dpctl.tensor as dpt @@ -188,11 +189,6 @@ def test_logaddexp_dtype_error( ar2 = dpt.ones_like(ar1, dtype="f4") y = dpt.zeros_like(ar1, dtype="int8") - assert_raises_regex( - ValueError, - "Output array of type.*is needed", - dpt.logaddexp, - ar1, - ar2, - y, - ) + with pytest.raises(ValueError) as excinfo: + dpt.logaddexp(ar1, ar2, out=y) + assert re.match("Output array of type.*is needed", str(excinfo.value)) diff --git a/dpctl/tests/elementwise/test_not_equal.py b/dpctl/tests/elementwise/test_not_equal.py index 63cc620d42..dae8464f17 100644 --- a/dpctl/tests/elementwise/test_not_equal.py +++ b/dpctl/tests/elementwise/test_not_equal.py @@ -128,7 +128,7 @@ def test_not_equal_broadcasting(): assert (dpt.asnumpy(r2) == expected).all() r3 = dpt.empty_like(m, dtype="?") - dpt.not_equal(m, v, r3) + dpt.not_equal(m, v, out=r3) assert (dpt.asnumpy(r3) == expected).all() diff --git a/dpctl/tests/elementwise/test_trigonometric.py b/dpctl/tests/elementwise/test_trigonometric.py index 1277bbe9c8..662f57fa4d 100644 --- a/dpctl/tests/elementwise/test_trigonometric.py +++ b/dpctl/tests/elementwise/test_trigonometric.py @@ -16,10 +16,11 @@ import itertools import os +import re import numpy as np import pytest -from numpy.testing import assert_allclose, assert_raises_regex +from numpy.testing import assert_allclose import dpctl.tensor as dpt from dpctl.tests.helper import get_queue_or_skip, skip_if_dtype_not_supported @@ -193,9 +194,9 @@ def test_trig_error_dtype(callable, dtype): x = dpt.zeros(5, dtype=dtype) y = dpt.empty_like(x, dtype="int16") - assert_raises_regex( - ValueError, "Output array of type.*is needed", callable, x, y - ) + with pytest.raises(ValueError) as excinfo: + callable(x, out=y) + assert re.match("Output array of type.*is needed", str(excinfo.value)) @pytest.mark.parametrize("np_call, dpt_call", _all_funcs) diff --git a/dpctl/tests/test_usm_ndarray_ctor.py b/dpctl/tests/test_usm_ndarray_ctor.py index c6f7537352..0c15038b47 100644 --- a/dpctl/tests/test_usm_ndarray_ctor.py +++ b/dpctl/tests/test_usm_ndarray_ctor.py @@ -1153,8 +1153,8 @@ def test_setitem_errors(): def test_setitem_different_dtypes(src_dt, dst_dt): q = get_queue_or_skip() skip_if_dtype_not_supported(dst_dt, q) - X = dpt.ones(10, src_dt, sycl_queue=q) - Y = dpt.zeros(10, src_dt, sycl_queue=q) + X = dpt.ones(10, dtype=src_dt, sycl_queue=q) + Y = dpt.zeros(10, dtype=src_dt, sycl_queue=q) Z = dpt.empty((20,), dtype=dst_dt, sycl_queue=q) Z[::2] = X Z[1::2] = Y @@ -1298,7 +1298,7 @@ def test_to_device(): def test_to_device_migration(): q1 = get_queue_or_skip() # two distinct copies of default-constructed queue q2 = get_queue_or_skip() - X1 = dpt.empty((5,), "i8", sycl_queue=q1) # X1 is associated with q1 + X1 = dpt.empty((5,), dtype="i8", sycl_queue=q1) # X1 is associated with q1 X2 = X1.to_device(q2) # X2 is reassociated with q2 assert X1.sycl_queue == q1 assert X2.sycl_queue == q2 @@ -1990,9 +1990,9 @@ def test_triu(dtype): X = dpt.reshape( dpt.arange(np.prod(shape), dtype=dtype, sycl_queue=q), shape ) - Y = dpt.triu(X, 1) + Y = dpt.triu(X, k=1) Xnp = np.arange(np.prod(shape), dtype=dtype).reshape(shape) - Ynp = np.triu(Xnp, 1) + Ynp = np.triu(Xnp, k=1) assert Y.dtype == Ynp.dtype assert np.array_equal(Ynp, dpt.asnumpy(Y)) @@ -2087,9 +2087,9 @@ def test_triu_order_k(order, k): shape, order=order, ) - Y = dpt.triu(X, k) + Y = dpt.triu(X, k=k) Xnp = np.arange(np.prod(shape), dtype="int").reshape(shape, order=order) - Ynp = np.triu(Xnp, k) + Ynp = np.triu(Xnp, k=k) assert Y.dtype == Ynp.dtype assert X.flags == Y.flags assert np.array_equal(Ynp, dpt.asnumpy(Y)) @@ -2108,9 +2108,9 @@ def test_tril_order_k(order, k): shape, order=order, ) - Y = dpt.tril(X, k) + Y = dpt.tril(X, k=k) Xnp = np.arange(np.prod(shape), dtype="int").reshape(shape, order=order) - Ynp = np.tril(Xnp, k) + Ynp = np.tril(Xnp, k=k) assert Y.dtype == Ynp.dtype assert X.flags == Y.flags assert np.array_equal(Ynp, dpt.asnumpy(Y)) @@ -2209,7 +2209,7 @@ def test_common_arg_validation(): def test_flags(): try: - x = dpt.empty(tuple(), "i4") + x = dpt.empty(tuple(), dtype="i4") except dpctl.SyclDeviceCreationError: pytest.skip("No SYCL devices available") f = x.flags diff --git a/dpctl/tests/test_usm_ndarray_indexing.py b/dpctl/tests/test_usm_ndarray_indexing.py index 7d431e0d0d..315f49baa9 100644 --- a/dpctl/tests/test_usm_ndarray_indexing.py +++ b/dpctl/tests/test_usm_ndarray_indexing.py @@ -1010,7 +1010,7 @@ def test_put_arg_validation(): x = dpt.arange(4, dtype="i4", sycl_queue=q) ind0 = dpt.arange(4, dtype=np.intp, sycl_queue=q) ind1 = dpt.arange(2.0, dtype="f", sycl_queue=q) - val = dpt.asarray(2, x.dtype, sycl_queue=q) + val = dpt.asarray(2, dtype=x.dtype, sycl_queue=q) with pytest.raises(TypeError): dpt.put(dict(), ind0, val, axis=0) diff --git a/dpctl/tests/test_usm_ndarray_manipulation.py b/dpctl/tests/test_usm_ndarray_manipulation.py index 4062fc02f8..e31e844aa6 100644 --- a/dpctl/tests/test_usm_ndarray_manipulation.py +++ b/dpctl/tests/test_usm_ndarray_manipulation.py @@ -1188,18 +1188,18 @@ def test_repeat_axes(): reps = 2 x = dpt.reshape(dpt.arange(5 * 10, dtype="i4"), (5, 10)) - expected_res = dpt.empty((x.shape[0] * 2, x.shape[1]), x.dtype) + expected_res = dpt.empty((x.shape[0] * 2, x.shape[1]), dtype=x.dtype) expected_res[::2, :], expected_res[1::2] = x, x res = dpt.repeat(x, reps, axis=0) assert dpt.all(res == expected_res) - expected_res = dpt.empty((x.shape[0], x.shape[1] * 2), x.dtype) + expected_res = dpt.empty((x.shape[0], x.shape[1] * 2), dtype=x.dtype) expected_res[:, ::2], expected_res[:, 1::2] = x, x res = dpt.repeat(x, reps, axis=1) assert dpt.all(res == expected_res) x = dpt.arange(10, dtype="i4") - expected_res = dpt.empty(x.shape[0] * reps, x.dtype) + expected_res = dpt.empty(x.shape[0] * reps, dtype=x.dtype) expected_res[::2], expected_res[1::2] = x, x res = dpt.repeat(x, reps, axis=0) assert dpt.all(res == expected_res) From 2c4c5a6582e31ba01ecc337d913bbd8fc7908115 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Sat, 23 Mar 2024 14:05:45 -0500 Subject: [PATCH 11/31] Docstring edits, added pos/kw arg delimeters to signature for reductions --- dpctl/tensor/_reduction.py | 48 +++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/dpctl/tensor/_reduction.py b/dpctl/tensor/_reduction.py index 6c0afbeebb..2879768f09 100644 --- a/dpctl/tensor/_reduction.py +++ b/dpctl/tensor/_reduction.py @@ -132,9 +132,8 @@ def _reduction_over_axis( return res -def sum(x, axis=None, dtype=None, keepdims=False): - """sum(x, axis=None, dtype=None, keepdims=False) - +def sum(x, /, *, axis=None, dtype=None, keepdims=False): + """ Calculates the sum of elements in the input array `x`. Args: @@ -166,6 +165,7 @@ def sum(x, axis=None, dtype=None, keepdims=False): * If `x` has a boolean data type, the returned array will have the default signed integral type for the device where input array `x` is allocated. + If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the sum. Default: `None`. @@ -194,9 +194,8 @@ def sum(x, axis=None, dtype=None, keepdims=False): ) -def prod(x, axis=None, dtype=None, keepdims=False): - """prod(x, axis=None, dtype=None, keepdims=False) - +def prod(x, /, *, axis=None, dtype=None, keepdims=False): + """ Calculates the product of elements in the input array `x`. Args: @@ -228,6 +227,7 @@ def prod(x, axis=None, dtype=None, keepdims=False): * If `x` has a boolean data type, the returned array will have the default signed integral type for the device where input array `x` is allocated. + If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the product. Default: `None`. @@ -256,9 +256,8 @@ def prod(x, axis=None, dtype=None, keepdims=False): ) -def logsumexp(x, axis=None, dtype=None, keepdims=False): - """logsumexp(x, axis=None, dtype=None, keepdims=False) - +def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False): + """ Calculates the logarithm of the sum of exponentials of elements in the input array `x`. @@ -283,6 +282,7 @@ def logsumexp(x, axis=None, dtype=None, keepdims=False): where input array `x` is allocated. * If `x` has a complex-valued floating-point data type, an error is raised. + If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. Default: `None`. @@ -313,9 +313,8 @@ def logsumexp(x, axis=None, dtype=None, keepdims=False): ) -def reduce_hypot(x, axis=None, dtype=None, keepdims=False): - """reduce_hypot(x, axis=None, dtype=None, keepdims=False) - +def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False): + """ Calculates the square root of the sum of squares of elements in the input array `x`. @@ -340,6 +339,7 @@ def reduce_hypot(x, axis=None, dtype=None, keepdims=False): where input array `x` is allocated. * If `x` has a complex-valued floating-point data type, an error is raised. + If the data type (either specified or resolved) differs from the data type of `x`, the input array elements are cast to the specified data type before computing the result. Default: `None`. @@ -423,9 +423,8 @@ def _comparison_over_axis(x, axis, keepdims, _reduction_fn): return res -def max(x, axis=None, keepdims=False): - """max(x, axis=None, keepdims=False) - +def max(x, /, *, axis=None, keepdims=False): + """ Calculates the maximum value of the input array `x`. Args: @@ -442,6 +441,7 @@ def max(x, axis=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the maxima. If the max was computed over the @@ -451,9 +451,8 @@ def max(x, axis=None, keepdims=False): return _comparison_over_axis(x, axis, keepdims, tri._max_over_axis) -def min(x, axis=None, keepdims=False): - """min(x, axis=None, keepdims=False) - +def min(x, /, *, axis=None, keepdims=False): + """ Calculates the minimum value of the input array `x`. Args: @@ -470,6 +469,7 @@ def min(x, axis=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the minima. If the min was computed over the @@ -538,9 +538,8 @@ def _search_over_axis(x, axis, keepdims, _reduction_fn): return res -def argmax(x, axis=None, keepdims=False): - """argmax(x, axis=None, keepdims=False) - +def argmax(x, /, *, axis=None, keepdims=False): + """ Returns the indices of the maximum values of the input array `x` along a specified axis. @@ -560,6 +559,7 @@ def argmax(x, axis=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the indices of the first occurrence of the @@ -570,9 +570,8 @@ def argmax(x, axis=None, keepdims=False): return _search_over_axis(x, axis, keepdims, tri._argmax_over_axis) -def argmin(x, axis=None, keepdims=False): - """argmin(x, axis=None, keepdims=False) - +def argmin(x, /, *, axis=None, keepdims=False): + """ Returns the indices of the minimum values of the input array `x` along a specified axis. @@ -592,6 +591,7 @@ def argmin(x, axis=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the indices of the first occurrence of the From d8df3012f5db23de9f143d3d0d3e02ac465189b6 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 09:03:04 -0500 Subject: [PATCH 12/31] Added new line to keep separation between definitions of adjacent functions to two line --- dpctl/tensor/_usmarray.pyx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dpctl/tensor/_usmarray.pyx b/dpctl/tensor/_usmarray.pyx index e98acbc3cf..0afb2099b4 100644 --- a/dpctl/tensor/_usmarray.pyx +++ b/dpctl/tensor/_usmarray.pyx @@ -1371,7 +1371,8 @@ cdef api void UsmNDArray_SetWritableFlag(usm_ndarray arr, int flag): """Set/unset USM_ARRAY_WRITABLE in the given array `arr`.""" arr._set_writable_flag(flag) -cdef api object UsmNDArray_MakeSimpleFromMemory( + +cdef api object UsmNDArray_MakeSimplkeFromMemory( int nd, const Py_ssize_t *shape, int typenum, c_dpmem._Memory mobj, Py_ssize_t offset, char order ): From 7e5be272c805a8e2d58d9a1711fde111b2042cdf Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 09:03:19 -0500 Subject: [PATCH 13/31] Use position-only, keyword-only delimiters in definition of all/any --- dpctl/tensor/_utility_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dpctl/tensor/_utility_functions.py b/dpctl/tensor/_utility_functions.py index aab32327f2..2a9c5923bf 100644 --- a/dpctl/tensor/_utility_functions.py +++ b/dpctl/tensor/_utility_functions.py @@ -73,7 +73,7 @@ def _boolean_reduction(x, axis, keepdims, func): return res -def all(x, axis=None, keepdims=False): +def all(x, /, *, axis=None, keepdims=False): """all(x, axis=None, keepdims=False) Tests whether all input array elements evaluate to True along a given axis. @@ -101,7 +101,7 @@ def all(x, axis=None, keepdims=False): return _boolean_reduction(x, axis, keepdims, tri._all) -def any(x, axis=None, keepdims=False): +def any(x, /, *, axis=None, keepdims=False): """any(x, axis=None, keepdims=False) Tests whether any input array elements evaluate to True along a given axis. From c87d31bc60dc07d081de4090180222770f3e4e85 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 09:07:26 -0500 Subject: [PATCH 14/31] Fixed typo in API function in _usmarray --- dpctl/tensor/_usmarray.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/tensor/_usmarray.pyx b/dpctl/tensor/_usmarray.pyx index 0afb2099b4..4f4d75adbb 100644 --- a/dpctl/tensor/_usmarray.pyx +++ b/dpctl/tensor/_usmarray.pyx @@ -1372,7 +1372,7 @@ cdef api void UsmNDArray_SetWritableFlag(usm_ndarray arr, int flag): arr._set_writable_flag(flag) -cdef api object UsmNDArray_MakeSimplkeFromMemory( +cdef api object UsmNDArray_MakeSimpleFromMemory( int nd, const Py_ssize_t *shape, int typenum, c_dpmem._Memory mobj, Py_ssize_t offset, char order ): From 586a9df2e117393605f8f2874437d1f658696848 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 11:34:24 -0500 Subject: [PATCH 15/31] Insert positional/keyword arguments only delimites in signature of dpctl.utils --- dpctl/utils/__init__.py | 2 +- dpctl/utils/_compute_follows_data.pyx | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dpctl/utils/__init__.py b/dpctl/utils/__init__.py index 50dac796e5..e8978d675a 100644 --- a/dpctl/utils/__init__.py +++ b/dpctl/utils/__init__.py @@ -38,7 +38,7 @@ from ._onetrace_context import onetrace_enabled -def intel_device_info(dev): +def intel_device_info(dev, /): """intel_device_info(sycl_device) For Intel(R) GPU devices returns a dictionary diff --git a/dpctl/utils/_compute_follows_data.pyx b/dpctl/utils/_compute_follows_data.pyx index 25c196764c..6c1b52c815 100644 --- a/dpctl/utils/_compute_follows_data.pyx +++ b/dpctl/utils/_compute_follows_data.pyx @@ -48,7 +48,7 @@ cdef bint queue_equiv(SyclQueue q1, SyclQueue q2): return q1.__eq__(q2) -def get_execution_queue(qs): +def get_execution_queue(qs, /): """ Given a list of :class:`dpctl.SyclQueue` objects returns the execution queue under compute follows data paradigm, or returns `None` if queues are not equal. @@ -71,7 +71,7 @@ def get_execution_queue(qs): return qs[0] -def get_coerced_usm_type(usm_types): +def get_coerced_usm_type(usm_types, /): """ Given a list of strings denoting the types of USM allocations for input arrays returns the type of USM allocation for the output array(s) per compute follows data paradigm. @@ -122,7 +122,7 @@ def _validate_usm_type_disallow_none(usm_type): ) -def validate_usm_type(usm_type, allow_none=True): +def validate_usm_type(usm_type, /, *, allow_none=True): """ validate_usm_type(usm_type, allow_none=True) Raises an exception if `usm_type` is invalid. From 7370c3f6712a4b31f9b03e88c87954ca81f01072 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 11:36:10 -0500 Subject: [PATCH 16/31] Fixed typo in the example --- examples/python/sycl_queue.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/python/sycl_queue.py b/examples/python/sycl_queue.py index fd18660ed8..573e472c26 100644 --- a/examples/python/sycl_queue.py +++ b/examples/python/sycl_queue.py @@ -81,7 +81,7 @@ def create_queue_from_subdevice_multidevice_context(): print(f"{cpu_d} has {cpu_d.max_compute_units} compute units") return ctx = dpctl.SyclContext(sub_devs) - q = dpctl.SyclQueue(ctx, sub_devs[0], partition="enable_profiling") + q = dpctl.SyclQueue(ctx, sub_devs[0], property="enable_profiling") print( "Number of devices in SyclContext " "associated with the queue: ", q.sycl_context.device_count, From 5bb0fe860f272a7df8b0a4f8dca9ddb5c2b08557 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 12:37:44 -0500 Subject: [PATCH 17/31] Use positional/keyword only args delimiter in manipulation functions --- dpctl/tensor/_manipulation_functions.py | 24 ++++++++++++------------ dpctl/tensor/_reshape.py | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/dpctl/tensor/_manipulation_functions.py b/dpctl/tensor/_manipulation_functions.py index 274ae75148..92a6df1913 100644 --- a/dpctl/tensor/_manipulation_functions.py +++ b/dpctl/tensor/_manipulation_functions.py @@ -83,7 +83,7 @@ def _broadcast_shapes(*args): return _broadcast_shape_impl(array_shapes) -def permute_dims(X, axes): +def permute_dims(X, /, axes): """permute_dims(x, axes) Permute the axes (dimensions) of an array; returns the permuted @@ -120,7 +120,7 @@ def permute_dims(X, axes): ) -def expand_dims(X, axis): +def expand_dims(X, /, *, axis=0): """expand_dims(x, axis) Expands the shape of an array by inserting a new axis (dimension) @@ -166,7 +166,7 @@ def expand_dims(X, axis): return dpt.reshape(X, shape) -def squeeze(X, axis=None): +def squeeze(X, /, axis=None): """squeeze(x, axis) Removes singleton dimensions (axes) from array `x`. @@ -211,7 +211,7 @@ def squeeze(X, axis=None): return dpt.reshape(X, new_shape) -def broadcast_to(X, shape): +def broadcast_to(X, /, shape): """broadcast_to(x, shape) Broadcast an array to a new `shape`; returns the broadcasted @@ -277,7 +277,7 @@ def broadcast_arrays(*args): return [broadcast_to(X, shape) for X in args] -def flip(X, axis=None): +def flip(X, /, *, axis=None): """flip(x, axis) Reverses the order of elements in an array `x` along the given `axis`. @@ -309,7 +309,7 @@ def flip(X, axis=None): return X[indexer] -def roll(X, shift, axis=None): +def roll(X, /, shift, *, axis=None): """ roll(x, shift, axis) @@ -467,7 +467,7 @@ def _concat_axis_None(arrays): return res -def concat(arrays, axis=0): +def concat(arrays, /, *, axis=0): """concat(arrays, axis) Joins a sequence of arrays along an existing axis. @@ -535,7 +535,7 @@ def concat(arrays, axis=0): return res -def stack(arrays, axis=0): +def stack(arrays, /, *, axis=0): """ stack(arrays, axis) @@ -596,7 +596,7 @@ def stack(arrays, axis=0): return res -def unstack(X, axis=0): +def unstack(X, /, *, axis=0): """unstack(x, axis=0) Splits an array in a sequence of arrays along the given axis. @@ -625,7 +625,7 @@ def unstack(X, axis=0): return tuple(Y[i] for i in range(Y.shape[0])) -def moveaxis(X, source, destination): +def moveaxis(X, source, destination, /): """moveaxis(x, source, destination) Moves axes of an array to new positions. @@ -714,7 +714,7 @@ def swapaxes(X, axis1, axis2): return dpt.permute_dims(X, tuple(ind)) -def repeat(x, repeats, axis=None): +def repeat(x, repeats, /, *, axis=None): """repeat(x, repeats, axis=None) Repeat elements of an array. @@ -930,7 +930,7 @@ def repeat(x, repeats, axis=None): return res -def tile(x, repetitions): +def tile(x, repetitions, /): """tile(x, repetitions) Repeat an input array `x` along each axis a number of times given by diff --git a/dpctl/tensor/_reshape.py b/dpctl/tensor/_reshape.py index 01693ad962..169b0c7f0f 100644 --- a/dpctl/tensor/_reshape.py +++ b/dpctl/tensor/_reshape.py @@ -87,7 +87,7 @@ def reshaped_strides(old_sh, old_sts, new_sh, order="C"): return new_sts if valid else None -def reshape(X, shape, order="C", copy=None): +def reshape(X, /, shape, *, order="C", copy=None): """reshape(x, shape, order="C") Reshapes array `x` into new shape. From 19185bf8615c65526aa23b72c59c7571c5528a81 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Mon, 25 Mar 2024 12:38:30 -0500 Subject: [PATCH 18/31] Adjusted tests to fix violations of keyword-arg given as positional --- dpctl/tests/test_usm_ndarray_manipulation.py | 93 +++++++++++--------- 1 file changed, 50 insertions(+), 43 deletions(-) diff --git a/dpctl/tests/test_usm_ndarray_manipulation.py b/dpctl/tests/test_usm_ndarray_manipulation.py index e31e844aa6..d75a3aa182 100644 --- a/dpctl/tests/test_usm_ndarray_manipulation.py +++ b/dpctl/tests/test_usm_ndarray_manipulation.py @@ -88,7 +88,7 @@ def test_permute_dims_2d_3d(shapes): def test_expand_dims_incorrect_type(): X_list = [1, 2, 3, 4, 5] with pytest.raises(TypeError): - dpt.permute_dims(X_list, 1) + dpt.permute_dims(X_list, axis=1) def test_expand_dims_0d(): @@ -97,16 +97,16 @@ def test_expand_dims_0d(): Xnp = np.array(1, dtype="int64") X = dpt.asarray(Xnp, sycl_queue=q) - Y = dpt.expand_dims(X, 0) - Ynp = np.expand_dims(Xnp, 0) + Y = dpt.expand_dims(X, axis=0) + Ynp = np.expand_dims(Xnp, axis=0) assert_array_equal(Ynp, dpt.asnumpy(Y)) - Y = dpt.expand_dims(X, -1) - Ynp = np.expand_dims(Xnp, -1) + Y = dpt.expand_dims(X, axis=-1) + Ynp = np.expand_dims(Xnp, axis=-1) assert_array_equal(Ynp, dpt.asnumpy(Y)) - pytest.raises(np.AxisError, dpt.expand_dims, X, 1) - pytest.raises(np.AxisError, dpt.expand_dims, X, -2) + pytest.raises(np.AxisError, dpt.expand_dims, X, axis=1) + pytest.raises(np.AxisError, dpt.expand_dims, X, axis=-2) @pytest.mark.parametrize("shapes", [(3,), (3, 3), (3, 3, 3)]) @@ -119,12 +119,12 @@ def test_expand_dims_1d_3d(shapes): X = dpt.asarray(Xnp, sycl_queue=q) shape_len = len(shapes) for axis in range(-shape_len - 1, shape_len): - Y = dpt.expand_dims(X, axis) - Ynp = np.expand_dims(Xnp, axis) + Y = dpt.expand_dims(X, axis=axis) + Ynp = np.expand_dims(Xnp, axis=axis) assert_array_equal(Ynp, dpt.asnumpy(Y)) - pytest.raises(np.AxisError, dpt.expand_dims, X, shape_len + 1) - pytest.raises(np.AxisError, dpt.expand_dims, X, -shape_len - 2) + pytest.raises(np.AxisError, dpt.expand_dims, X, axis=shape_len + 1) + pytest.raises(np.AxisError, dpt.expand_dims, X, axis=-shape_len - 2) @pytest.mark.parametrize( @@ -135,8 +135,8 @@ def test_expand_dims_tuple(axes): Xnp = np.empty((3, 3, 3), dtype="u1") X = dpt.asarray(Xnp, sycl_queue=q) - Y = dpt.expand_dims(X, axes) - Ynp = np.expand_dims(Xnp, axes) + Y = dpt.expand_dims(X, axis=axes) + Ynp = np.expand_dims(Xnp, axis=axes) assert_array_equal(Ynp, dpt.asnumpy(Y)) @@ -146,12 +146,12 @@ def test_expand_dims_incorrect_tuple(): except dpctl.SyclDeviceCreationError: pytest.skip("No SYCL devices available") with pytest.raises(np.AxisError): - dpt.expand_dims(X, (0, -6)) + dpt.expand_dims(X, axis=(0, -6)) with pytest.raises(np.AxisError): - dpt.expand_dims(X, (0, 5)) + dpt.expand_dims(X, axis=(0, 5)) with pytest.raises(ValueError): - dpt.expand_dims(X, (1, 1)) + dpt.expand_dims(X, axis=(1, 1)) def test_squeeze_incorrect_type(): @@ -456,9 +456,9 @@ def test_flip_0d(): Y = dpt.flip(X) assert_array_equal(Ynp, dpt.asnumpy(Y)) - pytest.raises(np.AxisError, dpt.flip, X, 0) - pytest.raises(np.AxisError, dpt.flip, X, 1) - pytest.raises(np.AxisError, dpt.flip, X, -1) + pytest.raises(np.AxisError, dpt.flip, X, axis=0) + pytest.raises(np.AxisError, dpt.flip, X, axis=1) + pytest.raises(np.AxisError, dpt.flip, X, axis=-1) def test_flip_1d(): @@ -468,12 +468,12 @@ def test_flip_1d(): X = dpt.asarray(Xnp, sycl_queue=q) for ax in range(-X.ndim, X.ndim): - Ynp = np.flip(Xnp, ax) - Y = dpt.flip(X, ax) + Ynp = np.flip(Xnp, axis=ax) + Y = dpt.flip(X, axis=ax) assert_array_equal(Ynp, dpt.asnumpy(Y)) - Ynp = np.flip(Xnp, 0) - Y = dpt.flip(X, 0) + Ynp = np.flip(Xnp, axis=0) + Y = dpt.flip(X, axis=0) assert_array_equal(Ynp, dpt.asnumpy(Y)) @@ -497,8 +497,8 @@ def test_flip_2d_3d(shapes): Xnp = np.arange(Xnp_size).reshape(shapes) X = dpt.asarray(Xnp, sycl_queue=q) for ax in range(-X.ndim, X.ndim): - Y = dpt.flip(X, ax) - Ynp = np.flip(Xnp, ax) + Y = dpt.flip(X, axis=ax) + Ynp = np.flip(Xnp, axis=ax) assert_array_equal(Ynp, dpt.asnumpy(Y)) @@ -569,8 +569,8 @@ def test_flip_multiple_axes(data): Xnp_size = np.prod(shape) Xnp = np.arange(Xnp_size).reshape(shape) X = dpt.asarray(Xnp, sycl_queue=q) - Y = dpt.flip(X, axes) - Ynp = np.flip(Xnp, axes) + Y = dpt.flip(X, axis=axes) + Ynp = np.flip(Xnp, axis=axes) assert_array_equal(Ynp, dpt.asnumpy(Y)) @@ -583,8 +583,10 @@ def test_roll_empty(): Y = dpt.roll(X, 1) Ynp = np.roll(Xnp, 1) assert_array_equal(Ynp, dpt.asnumpy(Y)) - pytest.raises(np.AxisError, dpt.roll, X, 1, 0) - pytest.raises(np.AxisError, dpt.roll, X, 1, 1) + with pytest.raises(np.AxisError): + dpt.roll(X, 1, axis=0) + with pytest.raises(np.AxisError): + dpt.roll(X, 1, axis=1) @pytest.mark.parametrize( @@ -605,12 +607,12 @@ def test_roll_1d(data): X = dpt.asarray(Xnp, sycl_queue=q) sh, ax = data - Y = dpt.roll(X, sh, ax) - Ynp = np.roll(Xnp, sh, ax) + Y = dpt.roll(X, sh, axis=ax) + Ynp = np.roll(Xnp, sh, axis=ax) assert_array_equal(Ynp, dpt.asnumpy(Y)) - Y = dpt.roll(X, sh, ax) - Ynp = np.roll(Xnp, sh, ax) + Y = dpt.roll(X, sh, axis=ax) + Ynp = np.roll(Xnp, sh, axis=ax) assert_array_equal(Ynp, dpt.asnumpy(Y)) @@ -644,8 +646,8 @@ def test_roll_2d(data): X = dpt.asarray(Xnp, sycl_queue=q) sh, ax = data - Y = dpt.roll(X, sh, ax) - Ynp = np.roll(Xnp, sh, ax) + Y = dpt.roll(X, sh, axis=ax) + Ynp = np.roll(Xnp, sh, axis=ax) assert_array_equal(Ynp, dpt.asnumpy(Y)) @@ -664,10 +666,14 @@ def test_roll_validation(): def test_concat_incorrect_type(): Xnp = np.ones((2, 2)) - pytest.raises(TypeError, dpt.concat) - pytest.raises(TypeError, dpt.concat, []) - pytest.raises(TypeError, dpt.concat, Xnp) - pytest.raises(TypeError, dpt.concat, [Xnp, Xnp]) + with pytest.raises(TypeError): + dpt.concat() + with pytest.raises(TypeError): + dpt.concat([]) + with pytest.raises(TypeError): + dpt.concat(Xnp) + with pytest.raises(TypeError): + dpt.concat([Xnp, Xnp]) def test_concat_incorrect_queue(): @@ -719,7 +725,7 @@ def test_concat_incorrect_shape(data): X = dpt.ones(Xshape, sycl_queue=q) Y = dpt.ones(Yshape, sycl_queue=q) - pytest.raises(ValueError, dpt.concat, [X, Y], axis) + pytest.raises(ValueError, dpt.concat, [X, Y], axis=axis) @pytest.mark.parametrize( @@ -827,7 +833,8 @@ def test_stack_incorrect_shape(): X = dpt.ones((1,), sycl_queue=q) Y = dpt.ones((2,), sycl_queue=q) - pytest.raises(ValueError, dpt.stack, [X, Y], 0) + with pytest.raises(ValueError): + dpt.stack([X, Y], axis=0) @pytest.mark.parametrize( @@ -1111,7 +1118,7 @@ def test_unstack_axis1(): except dpctl.SyclDeviceCreationError: pytest.skip("No SYCL devices available") y = dpt.reshape(x_flat, (2, 3)) - res = dpt.unstack(y, 1) + res = dpt.unstack(y, axis=1) assert_array_equal(dpt.asnumpy(y[:, 0, ...]), dpt.asnumpy(res[0])) assert_array_equal(dpt.asnumpy(y[:, 1, ...]), dpt.asnumpy(res[1])) @@ -1124,7 +1131,7 @@ def test_unstack_axis2(): except dpctl.SyclDeviceCreationError: pytest.skip("No SYCL devices available") y = dpt.reshape(x_flat, (4, 5, 3)) - res = dpt.unstack(y, 2) + res = dpt.unstack(y, axis=2) assert_array_equal(dpt.asnumpy(y[:, :, 0, ...]), dpt.asnumpy(res[0])) assert_array_equal(dpt.asnumpy(y[:, :, 1, ...]), dpt.asnumpy(res[1])) From 8fed12b5d1f12be93fadb96e2c51586563fc63f9 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Tue, 26 Mar 2024 09:03:21 -0500 Subject: [PATCH 19/31] Added positional-only, keyword-only delimiters to fns from _copy_utils --- dpctl/tensor/_copy_utils.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dpctl/tensor/_copy_utils.py b/dpctl/tensor/_copy_utils.py index 5ddb8c1a87..91ff9cdef2 100644 --- a/dpctl/tensor/_copy_utils.py +++ b/dpctl/tensor/_copy_utils.py @@ -108,7 +108,7 @@ def _copy_from_numpy_into(dst, np_ary): ) -def from_numpy(np_ary, device=None, usm_type="device", sycl_queue=None): +def from_numpy(np_ary, /, *, device=None, usm_type="device", sycl_queue=None): """ from_numpy(arg, device=None, usm_type="device", sycl_queue=None) @@ -147,7 +147,7 @@ def from_numpy(np_ary, device=None, usm_type="device", sycl_queue=None): return _copy_from_numpy(np_ary, usm_type=usm_type, sycl_queue=q) -def to_numpy(usm_ary): +def to_numpy(usm_ary, /): """ to_numpy(usm_ary) @@ -501,7 +501,7 @@ def _empty_like_triple_orderK(X1, X2, X3, dt, res_shape, usm_type, dev): return dpt.permute_dims(R, inv_perm) -def copy(usm_ary, order="K"): +def copy(usm_ary, /, *, order="K"): """copy(ary, order="K") Creates a copy of given instance of :class:`dpctl.tensor.usm_ndarray`. @@ -566,7 +566,7 @@ def copy(usm_ary, order="K"): def astype( - usm_ary, newdtype, /, order="K", casting="unsafe", *, copy=True, device=None + usm_ary, newdtype, /, *, order="K", casting="unsafe", copy=True, device=None ): """ astype(array, new_dtype, order="K", casting="unsafe", \ copy=True, device=None) From 63218b9a3e59675b3ab4a45859871de1f6c4d4ce Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Tue, 26 Mar 2024 16:35:17 -0500 Subject: [PATCH 20/31] Insert positional-only/keyword-only delimiters Added two internal functions to __all__ list --- dpctl/tensor/_type_utils.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/dpctl/tensor/_type_utils.py b/dpctl/tensor/_type_utils.py index fd5f09392b..8f67a55168 100644 --- a/dpctl/tensor/_type_utils.py +++ b/dpctl/tensor/_type_utils.py @@ -487,7 +487,7 @@ def __repr__(self): return self._finfo.__repr__() -def can_cast(from_, to, casting="safe") -> bool: +def can_cast(from_, to, /, *, casting="safe") -> bool: """ can_cast(from, to, casting="safe") Determines if one data type can be cast to another data type according \ @@ -619,7 +619,7 @@ def result_type(*arrays_and_dtypes): return res_dt -def iinfo(dtype): +def iinfo(dtype, /): """iinfo(dtype) Returns machine limits for integer data types. @@ -648,7 +648,7 @@ def iinfo(dtype): return np.iinfo(dtype) -def finfo(dtype): +def finfo(dtype, /): """finfo(type) Returns machine limits for floating-point data types. @@ -693,7 +693,7 @@ def _supported_dtype(dtypes): return True -def isdtype(dtype, kind): +def isdtype(dtype, kind, /): """isdtype(dtype, kind) Returns a boolean indicating whether a provided `dtype` is @@ -786,6 +786,8 @@ def _default_accumulation_dtype_fp_types(inp_dt, q): "_acceptance_fn_reciprocal", "_acceptance_fn_default_binary", "_acceptance_fn_divide", + "_acceptance_fn_negative", + "_acceptance_fn_subtract", "_resolve_weak_types", "_weak_type_num_kind", "_strong_dtype_num_kind", From 0396c31991435135b9bfec699cfb99a25e3f46fa Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 28 Mar 2024 08:08:16 -0500 Subject: [PATCH 21/31] Fixed using keyword-only arg as positional in _linear_algebra_functions --- dpctl/tensor/_linear_algebra_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/tensor/_linear_algebra_functions.py b/dpctl/tensor/_linear_algebra_functions.py index 159cd60394..d0a2dd8eac 100644 --- a/dpctl/tensor/_linear_algebra_functions.py +++ b/dpctl/tensor/_linear_algebra_functions.py @@ -758,7 +758,7 @@ def matmul(x1, x2, out=None, dtype=None, order="K"): ) if appended_axes: - out = dpt.expand_dims(out, appended_axes) + out = dpt.expand_dims(out, axis=appended_axes) orig_out = out if res_dt != out.dtype: From 3a7fa7f62135eea5f9f6d3327e45c0d26146a525 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 28 Mar 2024 12:16:22 -0500 Subject: [PATCH 22/31] Removed positional only delimiter in isdtype per array API test failure --- dpctl/tensor/_type_utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/tensor/_type_utils.py b/dpctl/tensor/_type_utils.py index 8f67a55168..d8f6b8d28d 100644 --- a/dpctl/tensor/_type_utils.py +++ b/dpctl/tensor/_type_utils.py @@ -693,7 +693,7 @@ def _supported_dtype(dtypes): return True -def isdtype(dtype, kind, /): +def isdtype(dtype, kind): """isdtype(dtype, kind) Returns a boolean indicating whether a provided `dtype` is From 9a112879262d8370a40d9052f1f549e3bce068e5 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 28 Mar 2024 15:25:30 -0500 Subject: [PATCH 23/31] Define defgroup MemorySemantics for memory semantics tokens --- .../syclinterface/Support/MemOwnershipAttrs.h | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/libsyclinterface/include/syclinterface/Support/MemOwnershipAttrs.h b/libsyclinterface/include/syclinterface/Support/MemOwnershipAttrs.h index faac31cbe6..bf78857e78 100644 --- a/libsyclinterface/include/syclinterface/Support/MemOwnershipAttrs.h +++ b/libsyclinterface/include/syclinterface/Support/MemOwnershipAttrs.h @@ -28,6 +28,10 @@ #pragma once +/** + * @defgroup MemorySemantics Self-documenting memory ownership semantics tokens + */ + /** * @def __dpctl_give * @brief The __dpctl_give attribute indicates that a new object is returned and @@ -38,10 +42,13 @@ * free the object, he/she should make sure to use it exactly once as a value * for a __dpctl_take argument. However, the user is free to use the object as * he/she likes as a value to __dpctl_keep arguments. + * + * @ingroup MemorySemantics */ #ifndef __dpctl_give #define __dpctl_give #endif + /*! * @def __dpctl_take * @brief The __dpctl_take attribute indicates that the function "takes" over @@ -53,21 +60,28 @@ * function. If the pointer annotated with __dpctl_take is NULL then it is * treated as an error, since it may prevent the normal behavior of the * function. + * + * @ingroup MemorySemantics */ #ifndef __dpctl_take #define __dpctl_take #endif -#ifndef __dpctl_keep + /*! * @def __dpctl_keep * @brief The __dpctl_keep attribute indicates that the function only uses the * object and does not destroy it before returning. + * + * @ingroup MemorySemantics */ +#ifndef __dpctl_keep #define __dpctl_keep #endif + /*! * @def __dpctl_null * @brief The __dpctl_null attribute indicates that a NULL value is returned. + * @ingroup MemorySemantics */ #ifndef __dpctl_null #define __dpctl_null From 49af3aa0973099a5c520160a52edcde0191cd6b8 Mon Sep 17 00:00:00 2001 From: ndgrigorian <46709016+ndgrigorian@users.noreply.github.com> Date: Mon, 1 Apr 2024 17:20:53 -0700 Subject: [PATCH 24/31] Edit docstrings for `tile` and `repeat`, fix "usm_narray" typos (#1629) * Improves `tile` docstring * Improves `repeat` docstring * Fixed typos in `angle` and `reciprocal` docstrings * Fixed typos in docstrings for `permute_dims, `moveaxis`, and `swapaxes` * Fixes typo and grammar in `nonzero` docstring * Fixes a typo in `populate_params` in `blackscholes.pyx` example * Change to `broadcast-compatible` per PR review by @oleksandr-pavlyk --- dpctl/tensor/_elementwise_funcs.py | 4 +- dpctl/tensor/_indexing_functions.py | 2 +- dpctl/tensor/_manipulation_functions.py | 57 ++++++++++++------- .../usm_memory/blackscholes/blackscholes.pyx | 2 +- 4 files changed, 39 insertions(+), 26 deletions(-) diff --git a/dpctl/tensor/_elementwise_funcs.py b/dpctl/tensor/_elementwise_funcs.py index 526fb25462..5a47962bbd 100644 --- a/dpctl/tensor/_elementwise_funcs.py +++ b/dpctl/tensor/_elementwise_funcs.py @@ -2160,7 +2160,7 @@ Default: "K". Returns: - usm_narray: + usm_ndarray: An array containing the element-wise reciprocals. The returned array has a floating-point data type determined by the Type Promotion Rules. @@ -2195,7 +2195,7 @@ Default: "K". Returns: - usm_narray: + usm_ndarray: An array containing the element-wise phase angles. The returned array has a floating-point data type determined by the Type Promotion Rules. diff --git a/dpctl/tensor/_indexing_functions.py b/dpctl/tensor/_indexing_functions.py index 91c82a1849..65605ed626 100644 --- a/dpctl/tensor/_indexing_functions.py +++ b/dpctl/tensor/_indexing_functions.py @@ -326,7 +326,7 @@ def nonzero(arr): Return the indices of non-zero elements. - Returns the tuple of usm_narrays, one for each dimension + Returns a tuple of usm_ndarrays, one for each dimension of `arr`, containing the indices of the non-zero elements in that dimension. The values of `arr` are always tested in row-major, C-style order. diff --git a/dpctl/tensor/_manipulation_functions.py b/dpctl/tensor/_manipulation_functions.py index 92a6df1913..701465e221 100644 --- a/dpctl/tensor/_manipulation_functions.py +++ b/dpctl/tensor/_manipulation_functions.py @@ -95,7 +95,7 @@ def permute_dims(X, /, axes): `(0,1,...,N-1)` where `N` is the number of axes (dimensions) of `x`. Returns: - usm_narray: + usm_ndarray: An array with permuted axes. The returned array must has the same data type as `x`, is created on the same device as `x` and has the same USM allocation @@ -646,7 +646,7 @@ def moveaxis(X, source, destination, /): in the half-open interval `[-N, N)`. Returns: - usm_narray: + usm_ndarray: Array with moved axes. The returned array must has the same data type as `x`, is created on the same device as `x` and has the same @@ -693,7 +693,7 @@ def swapaxes(X, axis1, axis2): a valid `axis` must be in the half-open interval `[-N, N)`. Returns: - usm_narray: + usm_ndarray: Array with swapped axes. The returned array must has the same data type as `x`, is created on the same device as `x` and has the same USM @@ -717,32 +717,38 @@ def swapaxes(X, axis1, axis2): def repeat(x, repeats, /, *, axis=None): """repeat(x, repeats, axis=None) - Repeat elements of an array. + Repeat elements of an array on a per-element basis. Args: x (usm_ndarray): input array repeats (Union[int, Sequence[int, ...], usm_ndarray]): The number of repetitions for each element. - `repeats` is broadcast to fit the shape of the given axis. + + `repeats` must be broadcast-compatible with `N` where `N` is + `prod(x.shape)` if `axis` is `None` and `x.shape[axis]` + otherwise. + If `repeats` is an array, it must have an integer data type. - Otherwise, `repeats` must be a Python integer, tuple, list, or - range. + Otherwise, `repeats` must be a Python integer or sequence of + Python integers (i.e., a tuple, list, or range). axis (Optional[int]): The axis along which to repeat values. If `axis` is `None`, the - function repeats elements of the flattened array. - Default: `None`. + function repeats elements of the flattened array. Default: `None`. Returns: - usm_narray: - Array with repeated elements. - The returned array must have the same data type as `x`, is created - on the same device as `x` and has the same USM allocation type as - `x`. If `axis` is `None`, the returned array is one-dimensional, + usm_ndarray: + output array with repeated elements. + + If `axis` is `None`, the returned array is one-dimensional, otherwise, it has the same shape as `x`, except for the axis along which elements were repeated. + The returned array will have the same data type as `x`. + The returned array will be located on the same device as `x` and + have the same USM allocation type as `x`. + Raises: AxisError: if `axis` value is invalid. """ @@ -937,21 +943,28 @@ def tile(x, repetitions, /): `repetitions`. For `N` = len(`repetitions`) and `M` = len(`x.shape`): - - if `M < N`, `x` will have `N - M` new axes prepended to its shape - - if `M > N`, `repetitions` will have `M - N` new axes 1 prepended to it + + * If `M < N`, `x` will have `N - M` new axes prepended to its shape + * If `M > N`, `repetitions` will have `M - N` ones prepended to it Args: x (usm_ndarray): input array repetitions (Union[int, Tuple[int, ...]]): - The number of repetitions for each dimension. + The number of repetitions along each dimension of `x`. Returns: - usm_narray: - Array with tiled elements. - The returned array must have the same data type as `x`, - is created on the same device as `x` and has the same USM - allocation type as `x`. + usm_ndarray: + tiled output array. + + The returned array will have rank `max(M, N)`. If `S` is the + shape of `x` after prepending dimensions and `R` is + `repetitions` after prepending ones, then the shape of the + result will be `S[i] * R[i]` for each dimension `i`. + + The returned array will have the same data type as `x`. + The returned array will be located on the same device as `x` and + have the same USM allocation type as `x`. """ if not isinstance(x, dpt.usm_ndarray): raise TypeError(f"Expected usm_ndarray type, got {type(x)}.") diff --git a/examples/cython/usm_memory/blackscholes/blackscholes.pyx b/examples/cython/usm_memory/blackscholes/blackscholes.pyx index dbb64de154..b7d37993f3 100644 --- a/examples/cython/usm_memory/blackscholes/blackscholes.pyx +++ b/examples/cython/usm_memory/blackscholes/blackscholes.pyx @@ -135,7 +135,7 @@ def populate_params( """ populate_params(params, pl, ph, sl, sh, tl, th, rl, rh, vl, vh, seed) Args: - params: usm_narray + params: usm_ndarray Array of shape (n_opts, 5) to populate with price, strike, time to maturity, interest rate, volatility rate per option using uniform distribution with provided distribution parameters. From d9c07902d1abd4a58e7d32fe339c8da8b8271028 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Tue, 2 Apr 2024 14:43:59 -0500 Subject: [PATCH 25/31] Fix docstring of create_program_from_spirv This addresses issue pointed out by @ndgrigorian during PR review --- dpctl/program/_program.pyx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dpctl/program/_program.pyx b/dpctl/program/_program.pyx index f947bc084b..cd47f2b8ca 100644 --- a/dpctl/program/_program.pyx +++ b/dpctl/program/_program.pyx @@ -276,15 +276,15 @@ cpdef create_program_from_spirv(SyclQueue q, const unsigned char[:] IL, """ Creates a Sycl interoperability program from an SPIR-V binary. - We use the ``DPCTLKernelBundle_CreateFromOCLSpirv()`` C API function to + We use the :c:func:`DPCTLKernelBundle_CreateFromOCLSpirv` C API function to create a ``sycl::kernel_bundle`` object from an compiled SPIR-V binary file. Parameters: q (SyclQueue): The :class:`SyclQueue` for which the :class:`SyclProgram` is going to be built. - IL (const char[:]) : SPIR-V binary IL file for an OpenCL program. - copts (unicode) : Optional compilation flags that will be used + IL (bytes) : SPIR-V binary IL file for an OpenCL program. + copts (str) : Optional compilation flags that will be used when compiling the program. Returns: From 93ce1137e4c6137ed805eb5900e88e3592e459f0 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 4 Apr 2024 05:33:53 -0500 Subject: [PATCH 26/31] Edited docstrings in _memory.pyx Used property format to describe constructor arguments for MemoryUSM* objects. Corrected uses of escape quotes in docstrings. Populated docstring for __sycl_usm_array_interface__ --- dpctl/memory/_memory.pyx | 153 ++++++++++++++++++++++++++++----------- 1 file changed, 110 insertions(+), 43 deletions(-) diff --git a/dpctl/memory/_memory.pyx b/dpctl/memory/_memory.pyx index 4330ecd25c..ebee7c4338 100644 --- a/dpctl/memory/_memory.pyx +++ b/dpctl/memory/_memory.pyx @@ -270,25 +270,25 @@ cdef class _Memory: buffer.suboffsets = NULL # for pointer arrays only property nbytes: - """ Extent of this USM buffer in bytes. """ + """Extent of this USM buffer in bytes.""" def __get__(self): return self.nbytes property size: - """ Extent of this USM buffer in bytes. """ + """Extent of this USM buffer in bytes.""" def __get__(self): return self.nbytes property _pointer: """ USM pointer at the start of this buffer - represented in Python integer. + represented as Python integer. """ def __get__(self): return (self.memory_ptr) property _context: - """ :class:`dpctl.SyclContext` the USM pointer is bound to. """ + """:class:`dpctl.SyclContext` the USM pointer is bound to. """ def __get__(self): return self.queue.get_sycl_context() @@ -309,12 +309,12 @@ cdef class _Memory: return self.refobj property sycl_context: - """ :class:`dpctl.SyclContext` the USM pointer is bound to. """ + """:class:`dpctl.SyclContext` the USM pointer is bound to.""" def __get__(self): return self.queue.get_sycl_context() property sycl_device: - """ :class:`dpctl.SyclDevice` the USM pointer is bound to. """ + """:class:`dpctl.SyclDevice` the USM pointer is bound to.""" def __get__(self): return self.queue.get_sycl_device() @@ -350,6 +350,31 @@ cdef class _Memory: return _to_memory, (self.copy_to_host(), self.get_usm_type()) property __sycl_usm_array_interface__: + """ + Dictionary encoding information about USM allocation. + + Contains the following fields: + + * ``"data"`` (Tuple[int, bool]) + unified address space pointer presented as Python integer + and a Boolean value of 'writeable' flag. If ``False`` the + allocation is read-only. The return flag is always set to + writeable. + * ``"shape"`` (Tuple[int]) + Extent of array in bytes. Shape is always 1-tuple for + this object. + * ``"strides"`` (Options[Tuple[int]]) + Strides describing array layout, or ``None`` if allocation is + C-contiguous. Always ``None``. + * ``"typestr"`` (str) + Typestring encoding values of allocation. This field is always + set to ``"|u1"`` representing unsigned bytes. + * ``"version"`` (int) + Always ``1``. + * ``"syclobj"`` (:class:`dpctl.SyclQueue`) + Queue associated with this class instance. + + """ def __get__(self): cdef dict iface = { "data": ((self.memory_ptr), @@ -366,9 +391,9 @@ cdef class _Memory: """ get_usm_type(syclobj=None) - Returns the type of USM allocation using Sycl context carried by - `syclobj` keyword argument. Value of None is understood to query - against `self.sycl_context` - the context used to create the + Returns the type of USM allocation using :class:`dpctl.SyclContext` + carried by ``syclobj`` keyword argument. Value of ``None`` is understood + to query against ``self.sycl_context`` - the context used to create the allocation. """ cdef const char* kind @@ -399,9 +424,9 @@ cdef class _Memory: """ get_usm_type(syclobj=None) - Returns the type of USM allocation using Sycl context carried by - `syclobj` keyword argument. Value of None is understood to query - against `self.sycl_context` - the context used to create the + Returns the type of USM allocation using :class:`dpctl.SyclContext` + carried by ``syclobj`` keyword argument. Value of ``None`` is understood + to query against ``self.sycl_context`` - the context used to create the allocation. """ cdef const char* kind @@ -461,7 +486,7 @@ cdef class _Memory: cpdef copy_from_host(self, object obj): """ - Copy content of Python buffer provided by `obj` to instance memory. + Copy content of Python buffer provided by ``obj`` to instance memory. """ cdef const unsigned char[::1] host_buf = obj cdef Py_ssize_t buf_len = len(host_buf) @@ -569,8 +594,8 @@ cdef class _Memory: @staticmethod cdef SyclDevice get_pointer_device(DPCTLSyclUSMRef p, SyclContext ctx): """ - Returns sycl device used to allocate given pointer `p` in - given sycl context `ctx` + Returns sycl device used to allocate given pointer ``p`` in + given sycl context ``ctx`` """ cdef DPCTLSyclDeviceRef dref = DPCTLUSM_GetPointerDevice( p, ctx.get_context_ref() @@ -586,8 +611,8 @@ cdef class _Memory: get_pointer_type(p, ctx) Gives the SYCL(TM) USM pointer type, using ``sycl::get_pointer_type``, - returning one of 4 possible strings: 'shared', 'host', 'device', or - 'unknown'. + returning one of 4 possible strings: ``'shared'``, ``'host'``, + ``'device'``, or ``'unknown'``. Args: p: DPCTLSyclUSMRef @@ -596,9 +621,9 @@ cdef class _Memory: Python object providing :class:`dpctl.SyclContext` against which to query for the pointer type. Returns: - b'unknown' if the pointer does not represent USM allocation made - using the given context. Otherwise, returns b'shared', b'device', - or b'host' type of the allocation. + ``b'unknown'`` if the pointer does not represent USM allocation + made using given context. Otherwise, returns ``b'shared'``, + ``b'device'``, or ``b'host'`` type of the allocation. """ cdef _usm_type usm_ty = DPCTLUSM_GetPointerType( p, ctx.get_context_ref() @@ -640,11 +665,11 @@ cdef class _Memory: DPCTLSyclQueueRef QRef, object memory_owner=None ): r""" - Create appropriate `MemoryUSM*` object from pre-allocated + Create appropriate ``MemoryUSM*`` object from pre-allocated USM memory bound to SYCL context in the reference SYCL queue. - Memory will be freed by `MemoryUSM*` object for default - value of memory_owner keyword. The non-default value should + Memory will be freed by ``MemoryUSM*`` object for default + value of ``memory_owner`` keyword. The non-default value should be an object whose dealloc slot frees the memory. The object may not be a no-op dummy Python object to @@ -696,14 +721,28 @@ cdef class _Memory: cdef class MemoryUSMShared(_Memory): """ - MemoryUSMShared(nbytes, alignment=0, queue=None, copy=False) + MemoryUSMShared(nbytes, alignment=0, queue=None) An object representing allocation of SYCL USM-shared memory. - Non-positive ``alignment`` values are not ignored and - the allocator ``malloc_shared`` is used for allocation instead. - If ``queue`` is ``None`` a cached default-constructed - :class:`dpctl.SyclQueue` is used to allocate memory. + Args: + nbytes (int) + number of bytes to allocated. + Expected to be positive. + alignment (Optional[int]): + allocation alignment request. Non-positive + ``alignment`` values are not ignored and + the unaligned allocator ``sycl::malloc_device`` + is used to make allocation instead. + Default: `0`. + queue (Optional[:class:`dpctl.SyclQueue`]): + SYCL queue associated with return allocation + instance. Allocation is performed on the device + associated with the queue, and is bound to + SYCL context from the queue. + If ``queue`` is ``None`` a cached + default-constructed :class:`dpctl.SyclQueue` is + used to allocate memory. """ def __cinit__(self, other, *, Py_ssize_t alignment=0, SyclQueue queue=None, int copy=False): @@ -733,14 +772,28 @@ cdef class MemoryUSMShared(_Memory): cdef class MemoryUSMHost(_Memory): """ - MemoryUSMHost(nbytes, alignment=0, queue=None, copy=False) + MemoryUSMHost(nbytes, alignment=0, queue=None) An object representing allocation of SYCL USM-host memory. - Non-positive ``alignment`` values are not ignored and - the allocator ``malloc_host`` is used for allocation instead. - If ``queue`` is ``None`` a cached default-constructed - :class:`dpctl.SyclQueue` is used to allocate memory. + Args: + nbytes (int) + number of bytes to allocated. + Expected to be positive. + alignment (Optional[int]): + allocation alignment request. Non-positive + ``alignment`` values are not ignored and + the unaligned allocator ``sycl::malloc_device`` + is used to make allocation instead. + Default: `0`. + queue (Optional[:class:`dpctl.SyclQueue`]): + SYCL queue associated with return allocation + instance. Allocation is made in host memory accessible + to all device in te SYCL context from the queue. + Allocation is bound to SYCL context from the queue. + If ``queue`` is ``None`` a cached + default-constructed :class:`dpctl.SyclQueue` is + used to allocate memory. """ def __cinit__(self, other, *, Py_ssize_t alignment=0, SyclQueue queue=None, int copy=False): @@ -771,14 +824,28 @@ cdef class MemoryUSMHost(_Memory): cdef class MemoryUSMDevice(_Memory): """ - MemoryUSMDevice(nbytes, alignment=0, queue=None, copy=False) - - An object representing allocation of SYCL USM-device memory. - - Non-positive ``alignment`` values are not ignored and - the allocator ``malloc_device`` is used for allocation instead. - If ``queue`` is ``None`` a cached default-constructed - :class:`dpctl.SyclQueue` is used to allocate memory. + MemoryUSMDevice(nbytes, alignment=0, queue=None) + + Class representing allocation of SYCL USM-device memory. + + Args: + nbytes (int) + number of bytes to allocated. + Expected to be positive. + alignment (Optional[int]): + allocation alignment request. Non-positive + ``alignment`` values are not ignored and + the unaligned allocator ``sycl::malloc_device`` + is used to make allocation instead. + Default: `0`. + queue (Optional[:class:`dpctl.SyclQueue`]): + SYCL queue associated with return allocation + instance. Allocation is performed on the device + associated with the queue, and is bound to + SYCL context from the queue. + If ``queue`` is ``None`` a cached + default-constructed :class:`dpctl.SyclQueue` is + used to allocate memory. """ def __cinit__(self, other, *, Py_ssize_t alignment=0, SyclQueue queue=None, int copy=False): @@ -808,14 +875,14 @@ def as_usm_memory(obj): """ as_usm_memory(obj) - Converts Python object with `__sycl_usm_array_interface__` property + Converts Python object with ``__sycl_usm_array_interface__`` property to one of :class:`.MemoryUSMShared`, :class:`.MemoryUSMDevice`, or :class:`.MemoryUSMHost` instances depending on the type of USM allocation they represent. Raises: ValueError - When object does not expose the `__sycl_usm_array_interface__`, + When object does not expose the ``__sycl_usm_array_interface__``, or it is malformed TypeError When unexpected types of entries in the interface are encountered From c2c4072f8e5c13d1825abbf2f24c88e4be13b47b Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 4 Apr 2024 10:49:36 -0700 Subject: [PATCH 27/31] Resolves gh-1634 Corrects docstrings in `_accumulation.py` by adding documentation for `out` keyword to `cumulative_*` functions --- dpctl/tensor/_accumulation.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/dpctl/tensor/_accumulation.py b/dpctl/tensor/_accumulation.py index 4e130674d3..6a156fd673 100644 --- a/dpctl/tensor/_accumulation.py +++ b/dpctl/tensor/_accumulation.py @@ -261,6 +261,11 @@ def cumulative_sum( boolean indicating whether to include the initial value (i.e., the additive identity, zero) as the first value along the provided axis in the output. Default: `False`. + out (Optional[usm_ndarray]): + the array into which the result is written. + The data type of `out` must match the expected shape and the + expected data type of the result or (if provided) `dtype`. + If `None` then a new array is returned. Default: `None`. Returns: usm_ndarray: @@ -335,6 +340,11 @@ def cumulative_prod( boolean indicating whether to include the initial value (i.e., the additive identity, zero) as the first value along the provided axis in the output. Default: `False`. + out (Optional[usm_ndarray]): + the array into which the result is written. + The data type of `out` must match the expected shape and the + expected data type of the result or (if provided) `dtype`. + If `None` then a new array is returned. Default: `None`. Returns: usm_ndarray: @@ -410,6 +420,11 @@ def cumulative_logsumexp( boolean indicating whether to include the initial value (i.e., the additive identity, zero) as the first value along the provided axis in the output. Default: `False`. + out (Optional[usm_ndarray]): + the array into which the result is written. + The data type of `out` must match the expected shape and the + expected data type of the result or (if provided) `dtype`. + If `None` then a new array is returned. Default: `None`. Returns: usm_ndarray: From 03e9fbd2cbfdbfded2e4db9caed0f454f98738ff Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 4 Apr 2024 13:14:50 -0700 Subject: [PATCH 28/31] Fix docstrings for sum, prod, logsumexp, and reduce_hypot As pointed out by @vtavana --- dpctl/tensor/_reduction.py | 33 ++++++++++----------------------- 1 file changed, 10 insertions(+), 23 deletions(-) diff --git a/dpctl/tensor/_reduction.py b/dpctl/tensor/_reduction.py index 2879768f09..a9b43630ec 100644 --- a/dpctl/tensor/_reduction.py +++ b/dpctl/tensor/_reduction.py @@ -148,19 +148,15 @@ def sum(x, /, *, axis=None, dtype=None, keepdims=False): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. - * If `x` has a real-valued floating-point data type, - the returned array will have the default real-valued - floating-point data type for the device where input - array `x` is allocated. + * If `x` has a real- or complex-valued floating-point data + type, the returned array will have the same data type as + `x`. * If `x` has signed integral data type, the returned array will have the default signed integral type for the device where input array `x` is allocated. * If `x` has unsigned integral data type, the returned array will have the default unsigned integral type for the device where input array `x` is allocated. - * If `x` has a complex-valued floating-point data type, - the returned array will have the default complex-valued - floating-pointer data type for the device where input array `x` is allocated. * If `x` has a boolean data type, the returned array will have the default signed integral type for the device @@ -210,20 +206,15 @@ def prod(x, /, *, axis=None, dtype=None, keepdims=False): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. - * If `x` has a real-valued floating-point data type, - the returned array will have the default real-valued - floating-point data type for the device where input - array `x` is allocated. + * If `x` has a real- or complex-valued floating-point data + type, the returned array will have the same data type as + `x`. * If `x` has signed integral data type, the returned array will have the default signed integral type for the device where input array `x` is allocated. * If `x` has unsigned integral data type, the returned array will have the default unsigned integral type for the device where input array `x` is allocated. - * If `x` has a complex-valued floating-point data type, - the returned array will have the default complex-valued - floating-pointer data type for the device where input - array `x` is allocated. * If `x` has a boolean data type, the returned array will have the default signed integral type for the device where input array `x` is allocated. @@ -273,10 +264,8 @@ def logsumexp(x, /, *, axis=None, dtype=None, keepdims=False): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. - * If `x` has a real-valued floating-point data type, - the returned array will have the default real-valued - floating-point data type for the device where input - array `x` is allocated. + * If `x` has a real-valued floating-point data type, the + returned array will have the same data type as `x`. * If `x` has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array `x` is allocated. @@ -330,10 +319,8 @@ def reduce_hypot(x, /, *, axis=None, dtype=None, keepdims=False): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. - * If `x` has a real-valued floating-point data type, - the returned array will have the default real-valued - floating-point data type for the device where input - array `x` is allocated. + * If `x` has a real-valued floating-point data type, the + returned array will have the same data type as `x`. * If `x` has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array `x` is allocated. From 123092b53d81f86752f916e0e0ac5644a6c41aaa Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 4 Apr 2024 13:44:56 -0700 Subject: [PATCH 29/31] Tweaks to docstrings in _set_functions --- dpctl/tensor/_set_functions.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/dpctl/tensor/_set_functions.py b/dpctl/tensor/_set_functions.py index 1ef850b9ba..81023a0827 100644 --- a/dpctl/tensor/_set_functions.py +++ b/dpctl/tensor/_set_functions.py @@ -66,11 +66,11 @@ class UniqueInverseResult(NamedTuple): def unique_values(x: dpt.usm_ndarray) -> dpt.usm_ndarray: """unique_values(x) - Returns the unique elements of an input array x. + Returns the unique elements of an input array `x`. Args: x (usm_ndarray): - input array. The input with more than one dimension is flattened. + input array. Inputs with more than one dimension are flattened. Returns: usm_ndarray an array containing the set of unique elements in `x`. The @@ -152,7 +152,7 @@ def unique_counts(x: dpt.usm_ndarray) -> UniqueCountsResult: Args: x (usm_ndarray): - input array. The input with more than one dimension is flattened. + input array. Inputs with more than one dimension are flattened. Returns: tuple[usm_ndarray, usm_ndarray] a namedtuple `(values, counts)` whose @@ -278,7 +278,7 @@ def unique_inverse(x): Args: x (usm_ndarray): - input array. The input with more than one dimension is flattened. + input array. Inputs with more than one dimension are flattened. Returns: tuple[usm_ndarray, usm_ndarray] a namedtuple `(values, inverse_indices)` whose @@ -435,7 +435,7 @@ def unique_all(x: dpt.usm_ndarray) -> UniqueAllResult: Args: x (usm_ndarray): - input array. The input with more than one dimension is flattened. + input array. Inputs with more than one dimension are flattened. Returns: tuple[usm_ndarray, usm_ndarray, usm_ndarray, usm_ndarray] a namedtuple `(values, indices, inverse_indices, counts)` whose From b8107712578d9b7a8270a273b723b038eea94d7e Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 4 Apr 2024 14:51:56 -0700 Subject: [PATCH 30/31] Tweaks to docstrings for `take` and `put` --- dpctl/tensor/_indexing_functions.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dpctl/tensor/_indexing_functions.py b/dpctl/tensor/_indexing_functions.py index 65605ed626..05f386ca3f 100644 --- a/dpctl/tensor/_indexing_functions.py +++ b/dpctl/tensor/_indexing_functions.py @@ -39,7 +39,7 @@ def _get_indexing_mode(name): def take(x, indices, /, *, axis=None, mode="wrap"): """take(x, indices, axis=None, mode="wrap") - Takes elements from array along a given axis. + Takes elements from an array along a given axis at given indices. Args: x (usm_ndarray): @@ -123,8 +123,7 @@ def take(x, indices, /, *, axis=None, mode="wrap"): def put(x, indices, vals, /, *, axis=None, mode="wrap"): """put(x, indices, vals, axis=None, mode="wrap") - Puts values of an array into another array - along a given axis. + Puts values into an array along a given axis at given indices. Args: x (usm_ndarray): From 5ed388c8baa5a38425eda5b90a5a339577a7ff60 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 4 Apr 2024 15:09:35 -0700 Subject: [PATCH 31/31] Tweaks to statistical function docstrings `N-correction` becomes `N - correction` to avoid confusing subtraction with hyphenation --- dpctl/tensor/_statistical_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dpctl/tensor/_statistical_functions.py b/dpctl/tensor/_statistical_functions.py index 2b8e65d304..367f7960e0 100644 --- a/dpctl/tensor/_statistical_functions.py +++ b/dpctl/tensor/_statistical_functions.py @@ -289,7 +289,7 @@ def var(x, axis=None, correction=0.0, keepdims=False): Default: `None`. correction (Optional[float, int]): degrees of freedom adjustment. The divisor used in calculating the - variance is `N-correction`, where `N` corresponds to the total + variance is `N - correction`, where `N` corresponds to the total number of elements over which the variance is calculated. Default: `0.0`. keepdims (Optional[bool]): @@ -341,7 +341,7 @@ def std(x, axis=None, correction=0.0, keepdims=False): over the entire array. Default: `None`. correction (Optional[float, int]): degrees of freedom adjustment. The divisor used in calculating the - standard deviation is `N-correction`, where `N` corresponds to the + standard deviation is `N - correction`, where `N` corresponds to the total number of elements over which the standard deviation is calculated. Default: `0.0`. keepdims (Optional[bool]):